I am going to explain how to setup your development tools so that you can debug Drush commands in real time, as they run. I've tested these instructions on Mac OSX.

In a previous blog post I outlined how to configure PHPStorm and Xdebug so you can step through the code of a webpage as it is executed. This allowed you to set breakpoints and inspect the value of variables at specific points in the code. The same can be done for Drush commands. You will need to have configured your PHPStorm as described in the first blog post.

Add Drush code to PHPStorm

Drush can be added to PHPStorm as an external library. This will allow you to view the Drush code within PHPStorm so you can add break points to it later. 

1. In the project pane, double click external libraries, which appears at the bottom of the directories.

2. Click the plus button in the bottom left of the PHP popup window. Now use the file brower to find where Drush is installed on your system. Select the folder and click OK and OK again. Drush should now be listed as an external library.

3. Click the telephone button in PHPStorm so it starts listening for executed code.

Configuring Drush to tell PHPStorm it is running

In the command line where you normally run your Drush commands, first type the following command and press enter:

export PHP_OPTIONS="-dxdebug.remote_autostart=On -didekey=PHPSTORM -dremote_host=localhost -dprofiler_enable=1"

Now, when you run a Drush command it will be picked up by PHPStorm.

If you have put in a breakpoint, then execution of the command will pause at that point. For example, open index.php in your project and place a breakpoint next to a PHP function as shown in the image below. If you click between the line number and the code, a red spot will appear.

Now, at the same command prompt where you entered the export command above, run a Drush command, for example:

drush cc all

PHPStorm should open at the breakpoint. Now you can step through the code in the same way as before.

Executing the export command before running Drush commands will be a little time consuming. I recommend you add this to your .bashrc file or .bash_profile file in your home directory so it's available as soon as you open your terminal.

To stop PHPStorm opening every time you run a Drush command, simply press the telephone button again and hang up.