Skip to navigation
Command reference

runs Commands

View as Markdown

Manage runs

Output formatting flags (--json, --jq, and --template) are documented once in Output Formatting and are omitted from the tables below.

bctrl runs delete

Purge the artifacts of an ended Run while retaining its lifecycle and usage record. Active Runs must be stopped and their native execution retired before purging.

bctrl runs delete <runId> [flags]
FlagDescription
--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
--yesConfirm this destructive operation

bctrl runs files add

Bind an existing Space File to the Run. The Run’s cell keeps a copy at the returned runtimePath.

bctrl runs files add <runId> [flags]
FlagDescription
--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 runs files collect

Save a file from the Run’s workspace as an output File.

bctrl runs files collect <runId> [flags]
FlagDescription
--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 runs files get

Get one Run file.

bctrl runs files get <runId> <fileId> [flags]
FlagDescription
--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 runs files list

List a Run’s files: inputs bound to the Run with their copy state in its cell, and outputs the Run produced.

bctrl runs files list <runId> [flags]
FlagDescription
--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
--role <value>Query parameter role
--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 runs files remove

Remove a Run input from the Run’s cell. The Space File is kept.

bctrl runs files remove <runId> <fileId> [flags]
FlagDescription
--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
--yesConfirm this destructive operation

bctrl runs files retry

Copy a failed Run input into the cell again.

bctrl runs files retry <runId> <fileId> [flags]
FlagDescription
--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 runs files upload

Upload one durable Space File (at path, default uploads/<filename>) and bind it to this Run. The Run’s cell keeps a copy at the returned runtimePath; binding.state reports when it is ready.

bctrl runs files upload <runId> [flags]
FlagDescription
--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 runs get

Get one run using the simplified run resource.

bctrl runs get <runId> [flags]
FlagDescription
--query <json>Query object: inline JSON, @file, or - for stdin
--params <json>Alias for —query
--include <value>Query parameter include
--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 runs list

List runs across visible runtime work using the simplified run resource.

bctrl runs list [flags]
FlagDescription
--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
--status <value>Query parameter status
--space-id <value>Query parameter spaceId
--resource-id <value>Query parameter resourceId
--resource-type <value>Query parameter resourceType
--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 runs recordings get

Read one recording belonging to this Run. A succeeded recording includes a direct standalone MP4 download URL, expiry, SHA-256 and byte size. Partial capture is reported explicitly. Download URLs expire within five minutes and never outlive a View.

bctrl runs recordings get <runId> <recordingId> [flags]
FlagDescription
--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 runs recordings list

Read the whole-Run recording, including export progress and a direct standalone MP4 download with its SHA-256 when succeeded. Preserves historical Run access after Browser deletion. Purged artifacts are excluded. Download URLs expire within five minutes and never outlive a View.

bctrl runs recordings list <runId> [flags]
FlagDescription
--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
--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 runs stream

Stream ordered trace and runtime events for a run.

bctrl runs stream <runId> [flags]
FlagDescription
--query <json>Query object: inline JSON, @file, or - for stdin
--params <json>Alias for —query
--include <value>Query parameter include
--after <value>Query parameter after
--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)
--last-event-id <id>Resume the event stream after this event
--timeout-ms <milliseconds>End the stream after this duration (1–60000)
--max-events <number>End after this many SSE events (1–200)

bctrl runs trace list

List structured trace spans for a run.

bctrl runs trace list <runId> [flags]
FlagDescription
--query <json>Query object: inline JSON, @file, or - for stdin
--params <json>Alias for —query
--parent-id <value>Query parameter parentId
--kind <value>Query parameter kind
--status <value>Query parameter status
--resource-type <value>Query parameter resourceType
--cursor <value>Query parameter cursor
--order <value>Query parameter order
--limit <value>Query parameter limit
--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)