function drush_parse_command

8.0.x drush_parse_command()
6.x drush_parse_command()
7.x drush_parse_command()
3.x drush_parse_command()
4.x drush_parse_command()
5.x drush_parse_command()
master drush_parse_command()

Matches a commands array, as returned by drush_get_arguments, with the current command table.

Note that not all commands may be discoverable at the point-of-call, since Drupal modules can ship commands as well, and they are not available until after bootstrapping.

drush_parse_command returns a normalized command descriptor, which is an associative array. Some of its entries are:

  • callback arguments: an array of arguments to pass to the calback.
  • callback: the function to run. Usually, this is 'drush_command', which will determine the primary hook for the function automatically. Only specify a callback function if you need many commands to call the same function (e.g. drush_print_file).
  • invoke hooks: If TRUE (the default), Drush will invoke all of the pre and post hooks for this command. Set to FALSE to suppress hooks. This setting is ignored unless the command 'callback' is also set.
  • primary function: Drush will copy the 'callback' parameter here if necessary. This value should not be set explicitly; use 'callback' instead.
  • description: description of the command.
  • arguments: an array of arguments that are understood by the command. for help texts.
  • required-arguments: The minimum number of arguments that are required, or TRUE if all are required.
  • options: an array of options that are understood by the command. for help texts.
  • global-options: a list of options from the set of Drush global options (@see: drush_get_global_options()) that relate to this command. The help for these options will be included in the help output for this command.
  • examples: an array of examples that are understood by the command. for help texts.
  • scope: one of 'system', 'project', 'site'.
  • bootstrap: drupal bootstrap level (depends on Drupal major version). -1=no_bootstrap.
  • core: Drupal major version required.
  • drupal dependencies: drupal modules required for this command.
  • drush dependencies: other drush command files required for this command.
  • handle-remote-commands: set to TRUE if `drush @remote mycommand` should be executed locally rather than remotely dispatched. When this mode is set, the target site can be obtained via: drush_get_context('DRUSH_TARGET_SITE_ALIAS')
  • remote-tty: set to TRUE if Drush should force ssh to allocate a pseudo-tty when this command is being called remotely. Important for interactive commands. Remote commands that allocate a psedo-tty always print "Connection closed..." when done.
  • strict-option-handling: set to TRUE if drush should strictly separate local command cli options from the global options. Usually, drush allows global cli options and command cli options to be interspersed freely on the commandline. For commands where this flag is set, options are separated, with global options comming before the command names, and command options coming after, like so: drush --global-options command --command-options In this mode, the command options are no longer available via drush_get_option(); instead, they can be retrieved via: $args = drush_get_original_cli_args_and_options(); $args = drush_get_context('DRUSH_COMMAND_ARGS', array()); In this case, $args will contain the command args and options literally, exactly as they were entered on the command line, and in the same order as they appeared.
  • 'outputformat': declares the data format to be used to render the command result. In addition to the output format engine options listed below, each output format type can take additional metadata items that control the way that the output is rendered. See the comment in each particular output format class for information. The Drush core output format engines can be found in commands/core/outputformat.

    • 'default': The default type to render output as. If declared, the command should not print any output on its own, but instead should return a data structure (usually an associative array) that can be rendered by the output type selected.
    • 'pipe-format': When the command is executed in --pipe mode, the command output will be rendered by the format specified by the pipe-format item instead of the default format. Note that in either event, the user may specify the format to use via the --format command-line option.
    • 'formatted-filter': specifies a function callback that will be used to filter the command result if the selected output formatter is NOT declared to be machine-parsable. "table" is an example of an output format that is not machine-parsable.
    • 'parsable-filter': function callback that will be used to filter the command result if the selected output formatter is declared to be machine-parsable. "var_export" is an example of an output format that is machine-parsable.
    • 'output-data-type': An identifier representing the data structure that the command returns. a description of the supported values.
    • 'field-labels': A mapping from machine name to human-readable name for all of the fields in a table-format command result. All possible field names should appear in this list.
    • 'fields-default': A list of the machine names of the fields that should be displayed by default in tables.
    • 'private-fields': A list of any fields that contain sensitive information, such as passwords. By default, Drush will hide private fields before printing the results to the console, but will include them in backend invoke results. Use --show-passwords to display.
    • 'column-widths': A mapping from field machine name to the column width that should be used in table output. Drush will automatically calculate the width of any field not listed here based on the length of the data items in it.
  • engines: declares information on Drush engines the command will load. Available engines can vary by command type.

Return value

bool|array A command definition.

See also

outputformat_drush_engine_outputformat() for

3 calls to drush_parse_command()
BaseBoot::bootstrap_and_dispatch in lib/Drush/Boot/BaseBoot.php
Main entrypoint to bootstrap the selected CMS and execute the selected command.
drush_preflight_command_dispatch in includes/
Handle any command preprocessing that may need to be done, including potentially redispatching the command immediately (e.g. for remote commands).
drush_redispatch_get_options in includes/
Get the options that were passed to the current command.


includes/, line 1327
The drush command engine.


function drush_parse_command() {
  $args = drush_get_arguments();
  $command = FALSE;

  // Get a list of all implemented commands.
  $implemented = drush_get_commands();
  if (!empty($args) && isset($implemented[$args[0]])) {
    $command = $implemented[$args[0]];
    $arguments = array_slice($args, 1);

  // We have found a command that matches. Set the appropriate values.
  if ($command) {
    // Special case. Force help command if --help option was specified.
    if (drush_get_option('help')) {
      $arguments = array($command['command']);
      $command = $implemented['help'];
      $command['arguments'] = $arguments;
    else {
      _drush_prepare_command($command, $arguments);
  return $command;