If you find Xdebug useful, please consider supporting the project.

Command Line Debug Client

The command line debug client allows you to debug PHP scripts without having to set up an IDE.


A binary for Linux, macOS, and Windows is available on the downloads page. You only have to download the binary, which you can then run from a command line.

Command Line Options

The following command line options are available:

-1 Debug once and then exit
-h Show this help
-p value  Specify the port to listen on [9000]. This is the same port that Xdebug should initiate a connection on. On the Xdebug side, this port can be configured with the xdebug.remote_port setting.
-v Show version number and exit
-x Show protocol XML. With this option enabled, the client will also show the raw XML data that the debugging engine sends back. This can be useful for debugging issues with the interaction between the debugger engine, for example Xdebug, and this client.


To start the client on the command line on Linux and macOS, open a shell, and then run:


On Windows, open a command a Command Prompt and run:


In both cases, you can add the command line options as described above.

When the debug client starts, it shows some version information. It will then wait until a connection is made to it by a debugging engine (such as Xdebug):

Xdebug Simple DBGp client (0.1)
Copyright 2019-2020 by Derick Rethans

Waiting for debug server to connect on port 9000.

After a connection is received, the debug client shows basic information, and then shows the (cmd) prompt and waits for input:

Connect from [::1]:51884
DBGp/1.0: Xdebug 2.9.2 — For PHP 7.4.3-dev
Debugging file:///tmp/xdebug-test-2.php (ID: 5242/dr)

On this command prompt you can then enter the available DBGp commands. With {tab} you can auto complete your command. You can use arrow up to a previous line, and use ctrl-R to search through your previous issued commands.

Here we step into the next line (the first line, in our case), and see which variables are available:

(cmd) step_into
1 | step_into > break/ok
1 | file:///tmp/xdebug-test-2.php:14

(cmd) context_get
2 | context_get
2 | uninitialized $a

The following commands and options are common:

breakpoint_set -t line -f file:///xdebug-test-2.php -n 5 Sets a breakpoint on line 5 of file:///xdebug-test-2.php
step_intoSteps to the next executable line in the code
runRuns the script until the next breakpoint, or when the script ends
context_getLists the variables and their values in the current scope
property_get -n $a Retrieves the value of the property $n

There is a full description in the DBGp documentation.

You can abort the debugging session, and then the client, with ctrl-C.