Drush commands¶

The base Tool module ships four Drush commands for working with tools from the command line. They need no submodule.

tool:list¶

List every registered tool.

drush tool:list

Aliases: tools, tlist.

Options:

--format: table (default) or markdown. Markdown prints full descriptions.
--operation: filter by operation. One of explain, read, transform, trigger, write.

# Only read-only tools, as markdown.
drush tool:list --operation=read --format=markdown

tool:search¶

Search tools by keyword against their label, ID, and description.

drush tool:search "email send"

Aliases: tsearch.

Options:

--match: or (default, match any keyword) or and (match all keywords).
--format: table (default) or markdown.
--operation: filter by operation, as above.

drush tool:search "email send" --match=and

tool:info¶

Show the full definition of one tool: its operation, flags, and input and output definitions.

drush tool:info send_email

Aliases: tinfo.

Options:

--format: table (default), markdown, or json.

The json format is useful for feeding a tool definition into other tooling.

tool:run¶

Execute a tool with the inputs you provide.

drush tool:run send_email --uid=2 --input='{"recipient":"test@example.com","subject":"Test","message":"Hello"}'

Aliases: trun.

Options:

--input: input values, either as a JSON object or as key=value pairs. Repeat the flag for multiple key=value inputs.
--json: print the result as JSON.
--uid: run as the given user ID. Omitting this option or passing --uid=0 runs as anonymous. Pass an explicit ID for an enabled account with the tool's required permissions. Use --uid=1 only for deliberate superuser execution.

The examples use user 2; replace this with an enabled account that has permission to run the tool. Invalid user IDs, missing accounts, and blocked accounts fail before the tool executes.

Use decimal user IDs without leading zeros, such as 7 rather than 007. An optional sign and surrounding whitespace are accepted, but the resulting user ID must be non-negative.

Malformed --input values fail instead of being ignored. JSON input must be an object containing named input values, not a scalar or a list. Input names in either format must be non-empty strings that PHP does not convert to integer keys. Values can contain nested JSON objects or arrays.

# key=value inputs, run as user 2.
drush tool:run send_email --uid=2 \
  --input=recipient=test@example.com \
  --input=subject=Test \
  --input=message=Hello

Because tool:run executes real actions, run it deliberately, especially for tools whose operation is write or trigger.

Exit codes¶

Successful commands return exit code 0. tool:run returns 1 for an unknown tool, invalid input or user, denied access, an execution error, or a failed result. tool:info returns 1 for an unknown tool. tool:list and tool:search return 1 for an invalid operation filter, and tool:search also returns 1 when no search keywords are provided. An empty list or a search with no matches is a successful result (0), not an error.