> 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.

# runShell

> Reference for the `runShell` schema.

## Referenced In

* [Markup definition](/reference/schemas/markup-definition)
* [test](/reference/schemas/test)
* [Resolved context](/reference/schemas/resolved-context)

## Fields

| Field    | Type                                                                                                     | Description                               | Default |
| :------- | :------------------------------------------------------------------------------------------------------- | :---------------------------------------- | :------ |
| runShell | one of: - string - object([Run shell command (detailed)](/reference/schemas/run-shell-command-detailed)) | Required. Perform a native shell command. | —       |

## Examples

```json
{
  "runShell": "docker run hello-world"
}
```

```json
{
  "runShell": {
    "command": "echo %USERNAME%",
    "shell": "cmd"
  }
}
```

```json
{
  "runShell": {
    "command": "[[ \"ok\" == o* ]] && echo bashism",
    "shell": "bash",
    "stdio": "bashism"
  }
}
```

```json
{
  "runShell": {
    "command": "echo",
    "args": [
      "$USER"
    ]
  }
}
```

```json
{
  "runShell": {
    "command": "echo",
    "args": [
      "hello-world"
    ]
  }
}
```

```json
{
  "runShell": {
    "command": "docker run hello-world",
    "timeout": 20000,
    "exitCodes": [
      0
    ],
    "stdio": "Hello from Docker!"
  }
}
```

```json
{
  "runShell": {
    "command": "false",
    "exitCodes": [
      1
    ]
  }
}
```

```json
{
  "runShell": {
    "command": "echo",
    "args": [
      "setup"
    ],
    "exitCodes": [
      0
    ],
    "stdio": "/.*?/"
  }
}
```

```json
{
  "runShell": {
    "command": "docker run hello-world",
    "workingDirectory": ".",
    "exitCodes": [
      0
    ],
    "stdio": "Hello from Docker!",
    "path": "docker-output.txt",
    "directory": "output",
    "maxVariation": 0.1,
    "overwrite": "aboveVariation"
  }
}
```

```json
{
  "runShell": {
    "command": "docker run -p 8080:80 nginx",
    "background": {
      "name": "web",
      "waitUntil": {
        "httpGet": "http://localhost:8080"
      }
    },
    "timeout": 30000
  }
}
```

```json
{
  "runShell": {
    "command": "docker run -p 5432:5432 -e POSTGRES_PASSWORD=test postgres:16",
    "background": {
      "name": "db",
      "waitUntil": {
        "port": 5432,
        "stdio": "/database system is ready to accept connections/"
      }
    },
    "timeout": 60000
  }
}
```