> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# Run shell command (detailed)

> Reference for the `Run shell command (detailed)` schema.

## Referenced In

* [runShell](/reference/schemas/runshell)
* [File type (executable)](/reference/schemas/file-type-executable)

## Fields

| Field            | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                     | Default          |
| :--------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------- |
| command          | string           | Required. Command to perform in the selected shell (see `shell`; defaults to `bash` on every platform).                                                                                                                                                                                                                                                                                                                         | —                |
| shell            | string           | Optional. Shell to run the command in. If unset, uses the config-level `shell` setting, which defaults to `bash`. `cmd` and `powershell` are only supported on Windows. On Windows, `bash` resolves to Git Bash, which Doc Detective installs automatically if it isn't present. Accepted values: `bash`, `cmd`, `powershell`                                                                                                   | —                |
| args             | array of string  | Optional. Arguments for the command.                                                                                                                                                                                                                                                                                                                                                                                            | `[]`             |
| workingDirectory | string           | Optional. Working directory for the command.                                                                                                                                                                                                                                                                                                                                                                                    | `.`              |
| exitCodes        | array of integer | Optional. Expected exit codes of the command. If the command's actual exit code isn't in this list, the step fails.                                                                                                                                                                                                                                                                                                             | `[0]`            |
| stdio            | string           | Optional. Content expected in the command's stdout or stderr. If the expected content can't be found in the command's stdout or stderr, the step fails. Supports strings and regular expressions. To use a regular expression, the string must start and end with a forward slash, like in `/^hello-world.*/`.                                                                                                                  | —                |
| path             | string           | Optional. File path to save the command's output, relative to `directory`.                                                                                                                                                                                                                                                                                                                                                      | —                |
| directory        | string           | Optional. Directory to save the command's output. If the directory doesn't exist, creates the directory. If not specified, the directory is your media directory.                                                                                                                                                                                                                                                               | —                |
| maxVariation     | number           | Optional. Allowed variation as a fraction (0 to 1) of text different between the current output and previously saved output. For example, 0.1 means 10%. If the difference between the current output and the previous output is greater than `maxVariation`, the step fails. If output doesn't exist at `path`, this value is ignored. Minimum: 0. Maximum: 1                                                                  | `0`              |
| overwrite        | string           | Optional. If `true`, overwrites the existing output at `path` if it exists. If `aboveVariation`, overwrites the existing output at `path` if the difference between the new output and the existing output is greater than `maxVariation`. Accepted values: `true`, `false`, `aboveVariation`                                                                                                                                   | `aboveVariation` |
| timeout          | integer          | Optional. Max time in milliseconds the command is allowed to run. If the command runs longer than this, the step fails. When `background` is set, this is instead the max time to wait for `background.waitUntil` to be satisfied before the step fails.                                                                                                                                                                        | `60000`          |
| background       | object           | Optional. Start the command as a long-running background process and return as soon as it is ready, instead of waiting for it to exit. When set, `exitCodes`, `stdio`, and output saving (`path`, `directory`, `maxVariation`, `overwrite`) are ignored, and `timeout` is the max time to wait for `waitUntil`. The process is owned by the run and is stopped by a `closeSurface` step or automatically when the run finishes. | —                |

## Examples

```json
{
  "command": "example",
  "shell": "bash",
  "args": [],
  "workingDirectory": ".",
  "exitCodes": [
    0
  ],
  "stdio": "example",
  "path": "example",
  "directory": "example",
  "maxVariation": 0,
  "overwrite": "aboveVariation",
  "timeout": 60000,
  "background": {
    "name": "example"
  }
}
```