CLI Overview

View as Markdown

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.

Install

$npm install -g @bctrl/cli

Verify the binary:

$bctrl --help
$bctrl version

Authenticate

For local use:

$bctrl auth login
$bctrl auth status

For CI and agents, set an API key:

$export BCTRL_API_KEY="bctrl_..."
$bctrl auth status --json

BCTRL_API_KEY takes precedence over stored login credentials. See Authentication.

A browser flow

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

$# 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

GroupPurpose
authLog in, inspect auth state, and print the active token.
spaceCreate and manage spaces and the space environment.
runtimeCreate, start, stop, configure, and move files through runtimes; create invocations.
runInspect run events, activity, files, live viewers, and recordings.
fileUpload, download, edit, and delete durable files.
vaultStore and read secrets and generate TOTP codes.
tool, toolset, tool-callDefine tools, bundle them into toolsets, and inspect tool calls.
ai-providerManage AI provider credentials.
proxyManage proxies and browse managed pools.
browser-extensionUpload, import, list, and delete browser extensions.
api-keyCreate, list, and revoke API keys.
subaccountManage subaccounts and their usage.
usageRead organization usage.
helpGet API, SDK, and CLI help.

Next