# Commands

drgn’s programmatic interface excels at complex analysis. For simpler tasks, it can be more convenient to use pre-defined commands. drgn provides a set of commands for this purpose.

In interactive mode, commands are accessed by starting a line with the `%` character.

In script mode, commands can be run with `drgn.commands.run_command()`.

Plugins and scripts can also register additional commands. See the commands API.

## Syntax

Most commands use shell syntax (words split on whitespace unless quoted or escaped, etc.) and command-line options:

    >>> %example --foo 'hello world'

Redirecting standard input, standard output, and standard error is supported:

    >>> %example > file
    >>> %example >> file
    >>> %example 2> err
    >>> %example < file

The output of a command can also be piped to an external command:

    >>> %example | grep foo | sort -r

Word expansions (including variable expansions, wildcards, etc.) are only supported in external commands (i.e., after the `|` in a pipeline).

A few commands have their own syntax. These commands do not support redirection or pipes.

## Common

The following commands are available when debugging any program.

### py

execute a python statement and allow shell redirection

#### Synopsis

py code

#### Description

Execute the given code, up to the first shell redirection or pipeline statement, as Python code.

For each occurrence of a pipeline operator (`|`) or any redirection operator (`<`, `>`, `<<`, `>>`), attempt to parse the preceding text as Python code. If the preceding text is syntactically valid code, then interpret the remainder of the command as shell redirections or pipelines, and execute the Python code with those redirections and pipelines applied.

The operators above can be used in syntactically valid Python. This means you need to be careful when using this function, and ensure that you wrap their uses with parentheses.

For example, consider the command: `%py field | MY_FLAG | grep foo`. While the intent here may be to execute the Python code `field | MY_FLAG` and pass its result to `grep`, that is not what will happen. The portion of text prior to the first `|` is valid Python, so it will be executed, and its output piped to the shell pipeline `MY_FLAG | grep foo`. Instead, running `%py (field | MY_FLAG) | grep foo` ensures that `field | MY_FLAG` gets piped to `grep foo`, because `(field` on its own is not valid Python syntax.

### sh

execute a shell command

#### Synopsis

sh [command]

#### Description

If command is given, run it with `sh -c --`. Otherwise, run an interactive shell with `sh -i`.

In either case, return the command’s exit status.

### source

run a drgn script

#### Synopsis

source script [args …]

#### Description

This loads and runs a drgn script in the current environment. Currently defined globals are available to the script, and globals defined by the script are added to the environment.

#### Positional Arguments

script

  script file path

args

  arguments to pass to the script

## Linux Kernel

The following commands are available when debugging the Linux kernel.

### crash

run a crash command

#### Synopsis

crash [command]

#### Description

This provides a compatibility mode emulating the crash utility.

If command is given, run the given crash command (which may include arguments, redirections, pipes, etc.). Otherwise, enter an interactive prompt where crash commands can be called directly.

Run `%crash help` or see Crash Compatibility for the list of commands.