> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://platform.bctrl.ai/v1/llms.txt

> 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 AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# browsers Commands

> Manage browsers

Manage browsers

Output formatting flags (`--json`, `--jq`, and `--template`) are documented once in [Output Formatting](/cli/output) and are omitted from the tables below.

## `bctrl browsers computer batch`

Execute up to twenty desktop actions in order on one current Browser Run. Every action is validated before acceptance. Execution stops at the first uncertain result and returns unknown with null data; earlier actions may have taken effect. Reusing the same Idempotency-Key replays the terminal result without repeating the batch.

```bash
bctrl browsers computer batch <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers computer click`

Click the current Browser Run at screenshot-pixel coordinates, or at the cursor when omitted. Button defaults to left; two or three clicks require the left button. An interrupted action returns unknown and must not be repeated automatically.

```bash
bctrl browsers computer click <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers computer clipboard read`

Read the system clipboard of the current Browser Run as text (at most 256 KiB of UTF-8). Reading has no effect on the page. The result carries its canonical Event ID; interrupted execution returns unknown.

```bash
bctrl browsers computer clipboard read <browserId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl browsers computer clipboard write`

Replace the system clipboard of the current Browser Run with text (at most 256 KiB of UTF-8, no NUL); empty text clears it. Nothing is pasted. The text is excluded from Events. Human control blocks automation; an interrupted write returns unknown.

```bash
bctrl browsers computer clipboard write <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers computer cursor`

Read the cursor position and desktop dimensions of the current Browser Run. The result carries its canonical Event ID. Human control blocks automation; interrupted execution returns unknown.

```bash
bctrl browsers computer cursor <browserId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl browsers computer doubleClick`

Double-click the left mouse button in the current Browser Run. Coordinates use screenshot pixels; omission uses the current cursor. An interrupted action returns unknown with its accepted Event ID.

```bash
bctrl browsers computer doubleClick <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers computer drag`

Drag the left mouse button in the current Browser Run to the requested coordinates, with an optional starting position and bounded path. Human control blocks automation. An interrupted action returns unknown.

```bash
bctrl browsers computer drag <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers computer key`

Send one bounded key chord to the current Browser Run, with an optional repeat count. Human control blocks automation. An interrupted action returns unknown with its accepted Event ID.

```bash
bctrl browsers computer key <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers computer move`

Move the cursor in the current Browser Run to screenshot-pixel coordinates. Human control blocks automation. An interrupted action returns unknown with its accepted Event ID.

```bash
bctrl browsers computer move <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers computer screenshot`

Capture the headed desktop of the current Browser Run as a JPEG. The result carries its canonical Event ID. An interrupted capture returns unknown with null data.

```bash
bctrl browsers computer screenshot <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers computer scroll`

Scroll the current Browser Run in the requested direction by a bounded amount, optionally at screenshot-pixel coordinates. Human control blocks automation. An interrupted action returns unknown.

```bash
bctrl browsers computer scroll <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers computer type`

Type text into the focused control in the current Browser Run. Text is excluded from canonical capability Events and replay results are encrypted. Human control blocks automation; an interrupted action returns unknown.

```bash
bctrl browsers computer type <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers computer wait`

Wait up to ten seconds in the current Browser Run. Human control blocks automation. The result carries its canonical Event ID; interrupted execution returns unknown.

```bash
bctrl browsers computer wait <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers connections revoke`

Invalidate every existing connection URL for the current Run and issue connections in a new credential generation. Refresh the browser before reconnecting.

```bash
bctrl browsers connections revoke <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |
| `--yes`                   | Confirm this destructive operation                 |

## `bctrl browsers control get`

Read desired control and native confirmation for the current Browser Run. The holder credential is never returned. A human hold persists across restarts, while old viewer credentials cannot control a newer Run.

```bash
bctrl browsers control get <browserId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl browsers control release`

Release control held by the supplied current viewer. Another viewer cannot release its hold. A stale epoch or ended Run is refused before mutation. Automation remains blocked until the native applied ACK. Interrupted delivery returns unknown with its canonical Event ID and must not be retried automatically.

```bash
bctrl browsers control release <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers control take`

Give a current input-enabled viewer human control of the Browser. The viewer credential must belong to this Browser and current Run, and its parent View must still permit input. The hold ends with that viewer. The result names the canonical control Event; an unconfirmed native ACK returns unknown. Reusing the same Idempotency-Key never repeats the transition.

```bash
bctrl browsers control take <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers create`

Create a reusable browser and durably request its first Run. Use wait to wait up to 60 seconds for startup; currentRun is null until a Run is admitted and connections appear after the browser starts.

```bash
bctrl browsers create [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--wait <value>`          | Query parameter wait                               |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers delete`

Delete the browser configuration and saved state, cancelling queued starts and stopping its current Run. Retained Run records remain readable.

```bash
bctrl browsers delete <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--yes`                   | Confirm this destructive operation                 |

## `bctrl browsers fetch`

Send an HTTP request from the browser itself: it carries the browser's cookies, proxy and TLS/HTTP2 fingerprint and is not subject to CORS. The response body is returned base64 encoded up to maxBytes (truncated is true beyond it). Human control blocks it; the Run's Events record the URL without its query, the status and the byte count. An interrupted request returns unknown and must not be repeated automatically.

```bash
bctrl browsers fetch <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers fetchStream`

Send an HTTP request from the browser itself, like fetch, and stream the response body back as it arrives, of any size and with bounded memory at every hop; a slow reader slows the upstream read. The upstream status is in BCTRL-Fetch-Status and its headers (JSON) in BCTRL-Fetch-Headers. A failure before the first byte is an error response; a failure after it aborts the stream, and the Run's completion Event records unknown. Human control blocks it.

```bash
bctrl browsers fetchStream <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |
| `--out <path>`            | Write binary content to a file, or - for stdout    |

## `bctrl browsers files delete`

Delete a file or directory of the current Browser Run; a non-empty directory needs recursive. Top-level directories and /files cannot be deleted. An interrupted deletion returns unknown.

```bash
bctrl browsers files delete <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--path <value>`          | Query parameter path                               |
| `--recursive <value>`     | Query parameter recursive                          |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--yes`                   | Confirm this destructive operation                 |

## `bctrl browsers files download`

Download one file of the current Browser Run (at most 1 GiB) as bytes. Headers carry its size and SHA-256.

```bash
bctrl browsers files download <browserId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--path <value>`       | Query parameter path                               |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--out <path>`         | Write binary content to a file, or - for stdout    |

## `bctrl browsers files list`

List a directory of the current Browser Run. The top level holds /downloads, /files (the Run's Space files, read only) and /workspace; nothing else of the machine is reachable. Pages are ordered by name and a cursor belongs to its Run.

```bash
bctrl browsers files list <browserId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--limit <value>`      | Query parameter limit                              |
| `--path <value>`       | Query parameter path                               |
| `--cursor <value>`     | Query parameter cursor                             |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl browsers files move`

Move or rename a file or directory of the current Browser Run within /downloads and /workspace. Set overwrite to replace the destination. An interrupted move returns unknown.

```bash
bctrl browsers files move <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers files upload`

Upload one file into /downloads or /workspace of the current Browser Run from multipart field file (at most 25 MiB). The file is written atomically; set overwrite to replace an existing file and createParents to create missing directories. An interrupted upload returns unknown.

```bash
bctrl browsers files upload <browserId> [flags]
```

| Flag                       | Description                                          |
| -------------------------- | ---------------------------------------------------- |
| `--query <json>`           | Query object: inline JSON, @file, or - for stdin     |
| `--params <json>`          | Alias for --query                                    |
| `--path <value>`           | Query parameter path                                 |
| `--overwrite <value>`      | Query parameter overwrite                            |
| `--create-parents <value>` | Query parameter createParents                        |
| `--space-id <value>`       | Query parameter spaceId                              |
| `--headers <json>`         | API headers: inline JSON, @file, or - for stdin      |
| `--api-version <date>`     | Dated API contract (default: 2026-10-03)             |
| `--space <id-or-name>`     | Select an authorized Space (BCTRL-Space)             |
| `--subaccount-id <id>`     | Effective subaccount context (BCTRL-Subaccount-Id)   |
| `--idempotency-key <key>`  | Retry key for this operation                         |
| `--file <path>`            | Upload a local file, or - for binary stdin           |
| `--fields <json>`          | Multipart fields: inline JSON, @file, or - for stdin |

## `bctrl browsers get`

Read a browser and its current Run. Use wait to wait for an accepted start or stop. Saved state remains private to the browser and is restored on its next Run.

```bash
bctrl browsers get <browserId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--wait <value>`       | Query parameter wait                               |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl browsers list`

List browser resources visible in the selected Space. A browser is running while it has a current Run and idle otherwise. Responses include the current Run and its connections when available.

```bash
bctrl browsers list [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--cursor <value>`     | Query parameter cursor                             |
| `--order <value>`      | Query parameter order                              |
| `--limit <value>`      | Query parameter limit                              |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--q <value>`          | Query parameter q                                  |
| `--name <value>`       | Query parameter name                               |
| `--location <value>`   | Query parameter location                           |
| `--status <value>`     | Query parameter status                             |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl browsers pages activate`

Bring one page of the current Browser Run to the front. Activation is confirmed by the browser, never assumed. Human control blocks automation; an interrupted action returns unknown.

```bash
bctrl browsers pages activate <browserId> <pageId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |

## `bctrl browsers pages close`

Close one page of the current Browser Run. Human control blocks automation. An interrupted action returns unknown and must not be repeated automatically.

```bash
bctrl browsers pages close <browserId> <pageId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--yes`                   | Confirm this destructive operation                 |

## `bctrl browsers pages get`

Read one open page of the current Browser Run: its URL, title and whether it is active. The result carries its canonical Event ID.

```bash
bctrl browsers pages get <browserId> <pageId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl browsers pages list`

List the open pages of the current Browser Run, ordered by Page ID. A cursor belongs to the Run that produced it. The result carries its canonical Event ID; interrupted execution returns unknown.

```bash
bctrl browsers pages list <browserId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--cursor <value>`     | Query parameter cursor                             |
| `--limit <value>`      | Query parameter limit                              |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl browsers pages navigate`

Navigate one page of the current Browser Run to an HTTP(S) URL and wait up to timeoutMs for its document. Human control blocks automation. An interrupted navigation returns unknown and must not be repeated automatically.

```bash
bctrl browsers pages navigate <browserId> <pageId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers pages open`

Open a new page in the current Browser Run at an HTTP(S) URL or about:blank, activated by default. Human control blocks automation. An interrupted action returns unknown and must not be repeated automatically.

```bash
bctrl browsers pages open <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers pages pdf`

Print one page of the current Browser Run to PDF. The document is returned base64 encoded. Interrupted execution returns unknown with null data.

```bash
bctrl browsers pages pdf <browserId> <pageId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers pages screenshot`

Capture one page of the current Browser Run as PNG or JPEG, optionally the full page. The image is returned base64 encoded. Interrupted execution returns unknown with null data.

```bash
bctrl browsers pages screenshot <browserId> <pageId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers recording get`

Read capture and MP4 export progress for the current Browser Run. Completed recordings are read through the historical Run recording routes. A succeeded recording includes a direct standalone MP4 URL, expiry, SHA-256 and byte size. Partial capture is reported explicitly. Download URLs expire within five minutes and never outlive a View.

```bash
bctrl browsers recording get <browserId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl browsers runs list`

List the retained Runs belonging to this browser, including ended and failed Runs, using cursor pagination.

```bash
bctrl browsers runs list <browserId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--cursor <value>`     | Query parameter cursor                             |
| `--order <value>`      | Query parameter order                              |
| `--limit <value>`      | Query parameter limit                              |
| `--space-id <value>`   | Query parameter spaceId                            |
| `--status <value>`     | Query parameter status                             |
| `--from <value>`       | Query parameter from                               |
| `--to <value>`         | Query parameter to                                 |
| `--include <value>`    | Query parameter include                            |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl browsers start`

Durably request a new Run of this browser, restoring its saved state. If a previous Run is stopping or saving, startup waits for it. An existing current Run is returned without starting another browser.

```bash
bctrl browsers start <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--wait <value>`          | Query parameter wait                               |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl browsers stop`

Request the current Run to stop. State saving continues in the background after the browser exits. Set discardState to erase saved state and skip saving this Run. Use wait to wait for the requested stop.

```bash
bctrl browsers stop <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--wait <value>`          | Query parameter wait                               |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |
| `--yes`                   | Confirm this destructive operation                 |

## `bctrl browsers update`

Update configuration used by the next Run. Changing stealth or viewport requires an idle browser without saved state or a queued start; stop with discardState first.

```bash
bctrl browsers update <browserId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--query <json>`          | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`         | Alias for --query                                  |
| `--space-id <value>`      | Query parameter spaceId                            |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |