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

# Command Reference

> The BCTRL CLI command tree - groups, subcommands, and key flags.

This reference summarizes the current CLI surface. For the exact flags on your installed version, run:

```bash
bctrl --help
bctrl <command> --help
bctrl <command> <subcommand> --help
```

## Global flags

These apply to data commands across the CLI:

| Flag                               | Purpose                                                      |
| ---------------------------------- | ------------------------------------------------------------ |
| `--json [fields]`                  | JSON output, with optional comma-separated field projection. |
| `--jq <expr>`                      | Filter JSON with a jq expression (requires `--json`).        |
| `--template <tpl>`                 | Format JSON with a Handlebars template (requires `--json`).  |
| `-L, --limit <n>` / `--cursor <c>` | Pagination on list commands.                                 |
| `-y, --yes`                        | Confirm destructive commands.                                |
| `--no-color`                       | Disable color output.                                        |

Write commands that take a request body (`create`, `patch`, and similar) also accept `--input <path>` to read JSON from a file, or `-` for stdin. It is per-command, not global, and appears below where it applies.

## auth

```bash
bctrl auth login            # add --with-token to read a key from stdin
bctrl auth status
bctrl auth token            # add --reveal to print to a terminal
bctrl auth logout
```

## space

```bash
bctrl space list            # --subaccount <id>  --query <text>
bctrl space get <space>
bctrl space create          # --name <name>  --subaccount-id <id>  --input <path>
bctrl space patch <space>   # --name <name>  --input <path>
bctrl space delete <space> --yes
bctrl space env get <space>
bctrl space env patch <space> --input env.json
```

## runtime

```bash
bctrl runtime list          # --space <id>  --status <status>
bctrl runtime get <runtime>
bctrl runtime create        # --space <id>  --name <name>  --config-file <path>
bctrl runtime patch <runtime>   # --name  --idle-timeout-minutes  --config-file
bctrl runtime start <runtime>   # --idempotency-key <key>
bctrl runtime stop <runtime>
bctrl runtime delete <runtime> --yes
```

Runtime files:

```bash
bctrl runtime file list <runtime>                 # --type <type>
bctrl runtime file upload <runtime> <local-path>  # --runtime-path  --name
bctrl runtime file stage <runtime>   --file <fileId> --runtime-path <path>
bctrl runtime file collect <runtime> --runtime-path <path> --destination-path <path>
```

Runtime invocations:

```bash
bctrl runtime invocation create <runtime> \
  --action extract --instruction "..." \
  --ai-provider <id> --model <model> --toolset <id> --timeout-ms <ms>
bctrl runtime invocation wait <runtime> <invocation>   # --timeout-ms <ms>
bctrl runtime invocation cancel <runtime> <invocation>
```

## run

```bash
bctrl run list              # --space  --runtime  --status  --subaccount
bctrl run get <run>
bctrl run activity list <run>    # --type --category --severity --invocation --file
bctrl run activity stream <run>
bctrl run events list <run>      # --type --status --page-id --context-id
bctrl run events stream <run>
bctrl run files list <run>       # --type <type>
bctrl run files export <run> --to run-files.zip
bctrl run invocations <run>      # --status --action
bctrl run invocation get <run> <invocation>
bctrl run live <run>             # --expires-in-seconds  --control <none|input>
bctrl run recording <run>        # --expires-in-seconds
```

## file

```bash
bctrl file list             # --space  --source  --prefix  --query
bctrl file get <file>
bctrl file upload <local-path>   # --space <id>  --path <storagePath>  --name
bctrl file download <file> --to <local-path>
bctrl file patch <file>     # --name  --metadata-file  --input
bctrl file delete <file> --yes
```

## vault

```bash
bctrl vault list            # --prefix  --origin  --has-totp
bctrl vault get <key>
bctrl vault read <key>      # --reveal to print to a terminal
bctrl vault set <key>       # --type <login|value>  --value  --username  --password ...
bctrl vault patch <key>     # update fields; --clear-totp  --clear-origins ...
bctrl vault delete <key> --yes
bctrl vault totp <key>
```

## tool, toolset, tool-call

```bash
bctrl tool list             # --space  --query  --status
bctrl tool get <tool>
bctrl tool create --input tool.json
bctrl tool patch <tool> --input patch.json
bctrl tool test <tool> --input input.json
bctrl tool delete <tool> --yes
bctrl tool version list <tool>
bctrl tool version create <tool> --input version.json
bctrl tool version get <tool> <version>
bctrl tool version promote <tool> <version>

bctrl toolset list          # --space
bctrl toolset get <toolset>
bctrl toolset create --input toolset.json
bctrl toolset patch <toolset> --input patch.json
bctrl toolset delete <toolset> --yes

bctrl tool-call list        # --tool  --run  --invocation  --status  --actor
bctrl tool-call get <tool-call>
```

## ai-provider

```bash
bctrl ai-provider list      # --provider  --name  --status
bctrl ai-provider get <provider>     # --include models
bctrl ai-provider create    # --name  --provider  --api-key  --default-model  --base-url
bctrl ai-provider patch <provider>
bctrl ai-provider test <provider>
bctrl ai-provider delete <provider> --yes
```

## proxy

```bash
bctrl proxy list
bctrl proxy get <proxy>
bctrl proxy create --input proxy.json
bctrl proxy patch <proxy> --input patch.json
bctrl proxy test <proxy>
bctrl proxy delete <proxy> --yes
bctrl proxy pool list       # --country  --category  --available
bctrl proxy pool get <pool>
```

## browser-extension

```bash
bctrl browser-extension list        # --subaccount-id  --q  --format  --source
bctrl browser-extension get <extension>
bctrl browser-extension upload <path>    # --name  --subaccount-id
bctrl browser-extension import --url <url>   # --name  --subaccount-id
bctrl browser-extension patch <extension>    # --name  --input
bctrl browser-extension delete <extension> --yes
```

## api-key, subaccount, usage

```bash
bctrl api-key list          # --subaccount-id  --kind <organization|subaccount>
bctrl api-key create        # --name  --subaccount-id  --expires-at
bctrl api-key delete <key> --yes

bctrl subaccount list       # --include-usage  --status  --external-id  --query
bctrl subaccount get <subaccount>    # --include usage
bctrl subaccount create     # --name  --external-id  --metadata-file
bctrl subaccount patch <subaccount>
bctrl subaccount archive <subaccount> --yes
bctrl subaccount usage [subaccount]

bctrl usage                 # organization usage

bctrl help                  # --topic <topic>  --audience <audience>
```