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

# CLI Overview

> Use the BCTRL CLI to authenticate, launch runtimes, inspect runs, move files, and script BCTRL from a terminal.

`bctrl` is a terminal interface for the v1 API, for local workflows, CI jobs, and coding agents that need command-line access to BCTRL resources.

Most data commands support `--json`, `--jq`, and `--template` for scripts and agents. See [Output & scripting](/cli/output).

## Install

```bash
npm install -g @bctrl/cli
```

Verify the binary:

```bash
bctrl --help
bctrl version
```

## Authenticate

For local use:

```bash
bctrl auth login
bctrl auth status
```

For CI and agents, set an API key:

```bash
export BCTRL_API_KEY="bctrl_..."
bctrl auth status --json
```

`BCTRL_API_KEY` takes precedence over stored login credentials. See [Authentication](/cli/auth).

## A browser flow

Create a runtime, start it, drive it, then inspect the run.

```bash
# Create a browser runtime
bctrl runtime create --name main --json

# Start it - returns a run-scoped connect URL and a runId
bctrl runtime start rt_123 --json

# Drive it: connect your own tooling to the connectUrl,
# or run a hosted agent invocation
bctrl runtime invocation create rt_123 \
  --action extract \
  --instruction "Extract the page title" \
  --json

# Inspect the run
bctrl run get run_123 --json
bctrl run events list run_123 --json

# Stop the runtime
bctrl runtime stop rt_123 --json
```

Scope a runtime to a space with `--space sp_123` on `runtime create`.

## Command groups

| Group                          | Purpose                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------ |
| `auth`                         | Log in, inspect auth state, and print the active token.                              |
| `space`                        | Create and manage spaces and the space environment.                                  |
| `runtime`                      | Create, start, stop, configure, and move files through runtimes; create invocations. |
| `run`                          | Inspect run events, activity, files, live viewers, and recordings.                   |
| `file`                         | Upload, download, edit, and delete durable files.                                    |
| `vault`                        | Store and read secrets and generate TOTP codes.                                      |
| `tool`, `toolset`, `tool-call` | Define tools, bundle them into toolsets, and inspect tool calls.                     |
| `ai-provider`                  | Manage AI provider credentials.                                                      |
| `proxy`                        | Manage proxies and browse managed pools.                                             |
| `browser-extension`            | Upload, import, list, and delete browser extensions.                                 |
| `api-key`                      | Create, list, and revoke API keys.                                                   |
| `subaccount`                   | Manage subaccounts and their usage.                                                  |
| `usage`                        | Read organization usage.                                                             |
| `help`                         | Get API, SDK, and CLI help.                                                          |

## Next

* [Quickstart](/cli/quickstart)
* [Authentication](/cli/auth)
* [Output & scripting](/cli/output)
* [Agents and CI](/cli/agents)
* [Command reference](/cli/reference)