The bro CLI — run and inspect the local router, launch coding agents, and manage your BitRouter Cloud account.

BitRouter ships as one static binary, bro, with no runtime dependencies to install. It runs the local router your applications call, launches supported coding agents, and exposes scriptable commands for routing, evaluation, optimization, and your hosted account.

Start with bro init for guided setup, bro serve for a foreground router, or bro code for BitRouter's coding conversation.

Every command below is generated from the binary's own --help, so the flags you see here are the flags your installed version accepts.

Conventions

Output is JSON by default for scriptable commands. The compatibility options --json, --human, and --context <NAME> go before the command when needed.
-c/--config <PATH> overrides config discovery for any command that loads a config. Discovery order: ./bitrouter.yaml → $BITROUTER_HOME/bitrouter.yaml → ~/.bitrouter/bitrouter.yaml → zero-config (in-memory defaults, auto-enabling providers from env keys).
Credentials live under $XDG_DATA_HOME/bitrouter/account-credentials.json (mode 0600), written by cloud login or providers login.

Environment variables

Variable	Effect
`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `OPENCODE_ZEN_API_KEY`	Zero-config BYOK — auto-enables the provider. See BYOK
`BITROUTER_API_KEY`	Cloud API key; enables the managed `bitrouter` provider
`BITROUTER_HOME`	Config discovery override (see above)
`BITROUTER_OAUTH_AS`	Override the OAuth authorization server for self-hosted Cloud
`OTEL_EXPORTER_OTLP_ENDPOINT`	Opt in to OTLP export. See OpenTelemetry

Command map

Run it — daemon lifecycle: lifecycle, request history, retained operations, and remote contexts
Onboard — init and config: the wizard, config validation
Inspect routing — routing introspection: decision preview, model catalog, OTel state
Providers — providers: catalog and subscription login
Evaluate and improve — policy: policies, evidence exchange, optimization, and trajectory history
Cloud — cloud: login, keys, usage, billing, policies, BYOK
Agents and protocols — agents, ACP, and MCP: agent catalog, ACP adapters, and upstream MCP checks
Skills — skills: inspect installed Agent Skills or scaffold one locally
Coding agents — coding agents: native launch, interactive conversation, and headless ACP runs
Misc — key, workflow-state, and update: virtual keys, benchmark tooling, self-update

The deprecated bitrouter command may still be installed as a compatibility alias, but documentation uses bro. Agents can operate BitRouter through the shipped Agent Skill; BitRouter's MCP support is an upstream client and aggregate gateway, not a first-party origin tool server.

Daemon lifecycle

The local router listens on http://127.0.0.1:4356 by default. It serves the supported model protocols and the configured upstream MCP aggregate; ACP agent adapters use their own stdio lifecycle. This section covers the daemon, request history, retained remote operations, and named remote contexts.

`bro serve`

Load a config, run migrations, and serve HTTP + control socket in the foreground

Usage: bro serve [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. When omitted, the binary resolves in this order: `./bitrouter.yaml` → `$BITROUTER_HOME/bitrouter.yaml` → `~/.bitrouter/bitrouter.yaml` → zero-config in-memory defaults (`bro init` is the explicit way to scaffold a file)

Runs in the foreground — the form you want under a process supervisor or in a container:

bro serve -c ./bitrouter.yaml

`bro start`

Spawn bro serve as a detached background process

Usage: bro start [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml` (passed through to the child)
`--log <LOG>`	Path to redirect the daemon's stdout/stderr to. Defaults to `bitrouter.log` inside the config file's directory (e.g. `~/.bitrouter/bitrouter.log`) so it lives alongside the socket and pid file rather than in the launcher's CWD

Daemonizes: writes a pidfile and detaches. stop/restart target the pidfile; reload hot-loads config changes without dropping in-flight connections.

`bro stop`

Send a stop command to a running daemon

Usage: bro stop [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml` (used to locate the control socket). Resolves via the standard chain: `./bitrouter.yaml` → `$BITROUTER_HOME/bitrouter.yaml` → `~/.bitrouter/bitrouter.yaml`
`--socket <SOCKET>`	Explicit control socket path. Overrides the config-derived path

`bro restart`

stop then start — config path is passed through

Usage: bro restart [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. When omitted, the binary resolves in this order: `./bitrouter.yaml` → `$BITROUTER_HOME/bitrouter.yaml` → `~/.bitrouter/bitrouter.yaml` → zero-config in-memory defaults (`bro init` is the explicit way to scaffold a file)
`--socket <SOCKET>`	Explicit control socket path. Overrides the config-derived path
`--log <LOG>`	Path to redirect the new daemon's stdout/stderr to. Defaults to `bitrouter.log` next to the config file

`bro reload`

Hot-reload the running daemon's config / routing table

Usage: bro reload [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml` (used to locate the control socket)
`--socket <SOCKET>`	Explicit control socket path. Overrides the config-derived path

`bro operations`

Inspect a retained remote administration operation

Usage: bro operations <COMMAND>

`bro operations show`

Show one retained reload operation owned by this credential

Usage: bro operations show --instance <INSTANCE> <REQUEST_ID>

Argument	Description
`<REQUEST_ID>`	Reload request UUID returned by `bro reload`

Flag	Description
`--instance <INSTANCE>`	Daemon boot instance UUID returned with the operation

`bro status`

Report a running daemon's status (pid, listen address, model count). Prints running: no when no daemon is reachable. With --requests, reports what the router has actually done instead: settled requests (time, model, the provider that actually served, tokens, cost, latency, status) plus daemon state and a spend rollup scoped to every caller. Read straight from the metering store, so it works with no daemon running. JSON by default like every other command; --human renders the table.

Usage: bro status [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml` (used to locate the control socket)
`--socket <SOCKET>`	Explicit control socket path. Overrides the config-derived path

Prints running: no when no daemon is reachable — safe to poll in scripts.

`bro requests`

Show recent settled requests and aggregate spend

Usage: bro requests [OPTIONS]

Flag	Description
`--limit <LIMIT>`	Maximum number of recent requests to return [default: 500]
`--since <SINCE>`	Inclusive RFC3339 lower bound. Requires `--until`
`--until <UNTIL>`	Exclusive RFC3339 upper bound. Requires `--since`
`--model <MODEL>`	Keep only requests resolved to this model id
`--provider <PROVIDER>`	Keep only requests served by this provider id
`-c, --config <CONFIG>`	Path to `bitrouter.yaml` (used to locate the local control socket)
`--socket <SOCKET>`	Explicit local control socket path

`bro context`

Manage named remote-control targets. Contexts store a token environment variable name, never the token value

Usage: bro context <COMMAND>

`bro context add`

Add a named remote target

Usage: bro context add --endpoint <ENDPOINT> --token-env <NAME> <NAME>

Argument	Description
`<NAME>`	Context name used by `--context`

Flag	Description
`--endpoint <ENDPOINT>`	HTTPS origin or endpoint ending in `/control/v1`. Plain HTTP is accepted only for loopback/SSH-forwarded endpoints
`--token-env <NAME>`	Environment variable containing this context's bearer token

`bro context list`

List configured remote targets

Usage: bro context list

`bro context show`

Show one remote target without reading its token

Usage: bro context show <NAME>

Argument	Description
`<NAME>`

`bro context remove`

Remove one remote target

Usage: bro context remove <NAME>

Argument	Description
`<NAME>`

Init and config

BitRouter discovers its config in this order — first hit wins:

./bitrouter.yaml in the current directory
$BITROUTER_HOME/bitrouter.yaml (must exist when the variable is set)
~/.bitrouter/bitrouter.yaml
Zero-config — in-memory defaults, auto-enabling any provider whose API key is set in the environment

Any command taking -c/--config overrides discovery. The daemon chdirs into the config's directory on startup, so relative paths (database.url, policy.path) resolve there. A JSON Schema for the config lives at dist/schema/bitrouter.config.schema.json in the repo for IDE autocomplete.

The full onboarding walkthrough — wizard steps, headless flags, recipes — is the Quickstart.

`bro init`

Guided onboarding wizard that sequences credential, harness, and finish steps to first value. Interactive by default; --yes (or no TTY) runs it headlessly, emitting the JSON result envelope and never blocking on a human. Every prompt has a flag equivalent (below) so an agent can drive the whole thing. Saves the default ACP harness and optional model in the resolved config or BitRouter home; --force resets existing settings

Usage: bro init [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Configuration to create/update; defaults to the resolved config or BitRouter home
`-y, --yes`	Run non-interactively: process the flags below, never block, emit the JSON envelope, and scaffold the starter config
`--force`	Allow overwriting an existing `bitrouter.yaml` when scaffolding
`--reset`	Clear stored onboarding credentials (cloud session always; provider credentials after a confirm, or unconditionally under `--yes`) before running
`--cloud-login`	(Step 1) Sign in to BitRouter Cloud via device-flow OAuth. Skipped and reported under `--yes` (a machine can't complete the device flow)
`--api-key <BRK_KEY>`	(Step 1) Seed the cloud credential from a `brk_` API key (non-interactive)
`--provider <ID>`	(Step 1) Log in to an upstream provider by id (repeatable). A paired `--provider-api-key` seeds it non-interactively; otherwise it is reported-and-skipped under `--yes`
`--provider-api-key <KEY>`	(Step 1) API key for the `--provider` at the same position (repeatable)
`--use-detected`	(Step 1) Accept the auto-detected credential(s) without prompting
`--harness <HARNESSES>`	(Step 2) Built-in ACP harness: `claude` or `codex` (first is the default) Possible values:
`- claude: Anthropic's Claude Code CLI (`claude`)`
`- codex:`	OpenAI's Codex CLI (`codex`)
`--after <AFTER>`	(Step 3) What to do at the end: `launch` \| `serve` \| `exit` Possible values:
`- launch: Open BitRouter's TUI using the selected ACP harness`
`- serve:`	Start the daemon and print a paste-in snippet for an existing tool
`- exit:`	Do nothing further
`--model <ID>`	(Step 3) Default daemon-routable model, saved for subsequent TUI sessions

Re-runs the wizard interactively; with --yes it never blocks and emits a JSON result envelope — the form an agent or CI should drive. Refuses to overwrite an existing bitrouter.yaml unless --force.

bro init --yes --use-detected --harness claude --after serve

`bro config`

Configuration tooling (validation against the published schema)

Usage: bro config <COMMAND>

`bro config validate`

Validate a config file: structure, provider derives resolution, and upstream-URL (SSRF) safety. Exits non-zero on an invalid config — safe to run in CI. Unset ${VAR} references are substituted with a placeholder and reported as warnings, so secrets need not be present

Usage: bro config validate [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml` / `bitrouter.json`. When omitted, the standard resolution chain applies (`./bitrouter.yaml` → `$BITROUTER_HOME` → `~/.bitrouter`)

The CI-safe check: exits non-zero when the config doesn't match the schema.

bro config validate -c ./bitrouter.yaml

Routing introspection

Three read-only views over the same routing state the daemon acts on. Use them to answer what would BitRouter do? before sending traffic.

`bro route`

Resolve a model name through the routing table. Uses the running daemon if reachable, otherwise loads the config — policy table included — and resolves locally. Read-only: nothing is sent upstream

Usage: bro route [OPTIONS] <MODEL>

Argument	Description
`<MODEL>`	The model name to resolve

Flag	Description
`--prompt <PROMPT>`	Prompt text to resolve for. The policy table keys on the agent-loop step a request represents, so the model it selects can differ with the prompt; omit for a bare model resolution
`-c, --config <CONFIG>`	Path to `bitrouter.yaml` (used as the standalone fallback and to locate the control socket)
`--socket <SOCKET>`	Explicit control socket path. Overrides the config-derived path

bro route anthropic/claude-opus-4.8
bro route @coding          # presets resolve through their bound policy

Uses the running daemon when reachable, otherwise resolves from the config on disk — so it works in CI too.

`bro models`

List routable models for a config, optionally filtered by provider

Usage: bro models [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. When omitted, the binary resolves in this order: `./bitrouter.yaml` → `$BITROUTER_HOME/bitrouter.yaml` → `~/.bitrouter/bitrouter.yaml` → zero-config in-memory defaults (`bro init` is the explicit way to scaffold a file)
`-p, --provider <PROVIDER>`	Show only models declared by this provider

bro models                 # every model id routable right now
bro models --provider anthropic

`bro observe`

Observability inspection (OTel exporter state, cardinality usage)

Usage: bro observe <COMMAND>

`bro observe status`

Report the OTel exporter's current state (endpoint, sampler, cardinality usage, in-flight spans). Queries the running daemon over the control socket; reports "stopped" + the compile-time OTEL_ENABLED flag when no daemon is reachable

Usage: bro observe status [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml` (used to locate the control socket)
`--socket <SOCKET>`	Explicit control socket path. Overrides the config-derived path

Reports the OTel exporter's live state — endpoint, sampler, cardinality usage, in-flight spans. The verification step for OpenTelemetry.

Providers

Two ways a provider becomes available: BYOK (its API key in the environment — see BYOK) and providers login (OAuth against subscription providers such as Claude or Codex subscriptions — see Model sources). providers list shows the catalog and which providers are active in the current config.

`bro providers`

Provider management

Usage: bro providers <COMMAND>

`bro providers list`

List every configured provider

Usage: bro providers list [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. When omitted, the binary resolves in this order: `./bitrouter.yaml` → `$BITROUTER_HOME/bitrouter.yaml` → `~/.bitrouter/bitrouter.yaml` → zero-config in-memory defaults (`bro init` is the explicit way to scaffold a file)
`--socket <SOCKET>`	Explicit local control socket for the daemon's accepted provider catalog

Log in to an upstream provider — interactive credential setup. Per-provider methods are auto-derived from the catalog: claude-code adopts the live Claude Code session; anthropic accepts an API-key paste; openai-codex runs the ChatGPT PKCE flow; github-copilot the GitHub device flow; everything else accepts a pasted API key. Logging in to the built-in bitrouter provider runs the same cloud sign-in as bro cloud login.

Usage: bro providers login [OPTIONS] <PROVIDER>

Argument	Description
`<PROVIDER>`	Provider id (e.g. `claude-code`, `openai-codex`, `bitrouter`)

Flag	Description
`-l, --label <LABEL>`	Account label this credential is stored under (default `default`). Ignored for the `bitrouter` provider (it uses the cloud credential) [default: default]
`--import-existing`	Import an existing vendor CLI session without prompting for a browser sign-in. Currently supported by openai-codex
`--no-browser`	Do not run a browser-based provider OAuth flow
`--api-key <KEY>`	Seed a BYOK provider non-interactively from this API key — skips the method menu and the stdin paste. The provider must accept a pasted key (OAuth-only backends reject it)
`--key-stdin`	Read the API key from stdin (one line) instead of prompting — for pipelines, e.g. `printf %s "$KEY" \| bro providers login openai --key-stdin`

bro providers login <provider-id>

Opens the provider's OAuth flow and stores the credential in the local credential store — no key to paste. providers logout removes it.

`bro providers logout`

Log out of an upstream provider — clears every stored credential for it. For the built-in bitrouter provider this is cloud logout

Usage: bro providers logout <PROVIDER>

Argument	Description
`<PROVIDER>`	Provider id whose stored credentials should be removed

Policy

Routing policies are the artifact the self-improving loop learns into: init scaffolds policy-lock.yaml and binds it to a preset, live traffic teaches the adequacy ledger, and evolve --apply folds proven downgrades back into the file. The walkthrough, table, and ledger semantics are in Adaptive routing.

bro policy create + bro key sign are a different surface — per-virtual-key access control (allowed models, budgets, rate limits), not routing. See Guardrails.

`bro policy`

Policy management

Usage: bro policy <COMMAND>

`bro policy create`

Write a starter access-control policy file to the policy dir

Usage: bro policy create [OPTIONS] <ID>

Argument	Description
`<ID>`	Policy id (becomes the file stem and the `id:` field)

Flag	Description
`--dir <DIR>`	Policy directory. Default matches the assembly default [default: ./policies]

`bro policy init`

Create a routing policy lock and bind it to a preset

Usage: bro policy init [OPTIONS] --preset <PRESET> --economy <ECONOMY> <NAME>

Argument	Description
`<NAME>`	Policy name written under `policies:`

Flag	Description
`--preset <PRESET>`	Preset users select as `@preset` or `@preset:variant`
`--strong <STRONG>`	Strong base model. Inferred from an existing preset when omitted
`--strong-effort <STRONG_EFFORT>`	Exact reasoning effort owned by the strong target
`--economy <ECONOMY>`	Economy model explored as a replacement
`--economy-effort <ECONOMY_EFFORT>`	Exact reasoning effort owned by the economy target
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`

bro policy init coding --preset coding \
  --economy moonshotai/kimi-k2.7-code

Writes policy-lock.yaml (strong/economy tiers, adequacy pre-seeded) and edits bitrouter.yaml comment-preservingly to bind the preset with writeback: locked.

`bro policy check`

Parse and cross-validate bitrouter.yaml and its policy lock

Usage: bro policy check [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`

`bro policy verify`

Verify the lock's compiled evidence root against the local ledger

Usage: bro policy verify [OPTIONS]

Flag	Description
`--evidence`
`-c, --config <CONFIG>`

`bro policy status`

Show policy path, digest, runtime mode, and preset bindings

Usage: bro policy status [OPTIONS]

Flag	Description
`--view <VIEW>`	Read `disk` locally by default; a remote context defaults to `active` [possible values: active, disk]
`-c, --config <CONFIG>`
`--socket <SOCKET>`	Explicit local control socket for an active policy read

`bro policy show`

Show one named policy after validation

Usage: bro policy show [OPTIONS] <NAME>

Argument	Description
`<NAME>`

Flag	Description
`--view <VIEW>`	Read `disk` locally by default; a remote context defaults to `active` [possible values: active, disk]
`-c, --config <CONFIG>`
`--socket <SOCKET>`	Explicit local control socket for an active policy read

`bro policy reload`

Hot-reload the policy lock through the daemon control socket

Usage: bro policy reload [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`
`--socket <SOCKET>`

Hot-reloads the daemon's policy snapshot. An invalid lock is rejected and the daemon keeps its last-known-good.

`bro policy compile`

Compile a deterministic v3 candidate without changing the active lock

Usage: bro policy compile [OPTIONS] --output <FILE>

Flag	Description
`--output <FILE>`	Candidate output path
`--snapshot-time <UNIX_MS>`	Frozen evidence snapshot time in Unix milliseconds
`--eval-snapshot <SHA256>`	Immutable admitted-evidence root from `eval snapshot freeze`
`-c, --config <CONFIG>`

`bro policy diff`

Compare explicit routes in two policy lock artifacts

Usage: bro policy diff <ACTIVE> <CANDIDATE>

Argument	Description
`<ACTIVE>`
`<CANDIDATE>`

`bro policy publish`

Publish one already-compiled candidate after lineage validation

Usage: bro policy publish [OPTIONS] <CANDIDATE>

Argument	Description
`<CANDIDATE>`

Flag	Description
`-c, --config <CONFIG>`
`--socket <SOCKET>`

`bro policy evolve`

Project qualified database evidence into a deterministic policy lock

Usage: bro policy evolve [OPTIONS]

Flag	Description
`--apply`	Publish the candidate. Without this flag, print a dry-run report
`--output <FILE>`	Export the candidate without changing the active policy lock
`-c, --config <CONFIG>`

bro policy evolve          # dry-run candidate projection
bro policy unlock
bro policy evolve --apply  # atomically republish policy-lock.yaml
bro policy lock

Only adds qualified routes — never overwrites or removes yours — and refuses to publish while writeback: locked.

`bro policy rollback`

Restore an exact lock snapshot from local promotion history

Usage: bro policy rollback [OPTIONS] <DIGEST>

Argument	Description
`<DIGEST>`

Flag	Description
`-c, --config <CONFIG>`
`--socket <SOCKET>`

`bro eval`

Evaluator-neutral evidence exchange

Usage: bro eval <COMMAND>

`bro eval subject`

Create, inspect, and list eval subjects

Usage: bro eval subject <COMMAND>

`bro eval subject seal`

Calculate the canonical evidence digest and write a validated JSON subject

Usage: bro eval subject seal --output <FILE> <DRAFT>

Argument	Description
`<DRAFT>`	Draft JSON or YAML subject with redacted evidence items

Flag	Description
`--output <FILE>`	Destination for the deterministic sealed JSON subject

`bro eval subject put`

Insert an immutable subject from JSON or YAML

Usage: bro eval subject put [OPTIONS] <FILE>

Argument	Description
`<FILE>`

Flag	Description
`-c, --config <CONFIG>`

`bro eval subject get`

Get one subject by eval id

Usage: bro eval subject get [OPTIONS] <EVAL_ID>

Argument	Description
`<EVAL_ID>`

Flag	Description
`-c, --config <CONFIG>`

`bro eval subject list`

List subjects

Usage: bro eval subject list [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`

`bro eval result`

Submit an evaluator result through authority admission

Usage: bro eval result <COMMAND>

`bro eval result submit`

Submit an immutable result from JSON or YAML as the local operator

Usage: bro eval result submit [OPTIONS] <FILE>

Argument	Description
`<FILE>`

Flag	Description
`-c, --config <CONFIG>`

`bro eval snapshot`

Freeze or inspect an immutable admitted-evidence snapshot

Usage: bro eval snapshot <COMMAND>

`bro eval snapshot freeze`

Freeze all currently admitted results into a content-addressed manifest

Usage: bro eval snapshot freeze [OPTIONS]

Flag	Description
`--at <AT>`
`-c, --config <CONFIG>`

`bro eval snapshot get`

Get a frozen manifest by evidence root

Usage: bro eval snapshot get [OPTIONS] <EVIDENCE_ROOT>

Argument	Description
`<EVIDENCE_ROOT>`

Flag	Description
`-c, --config <CONFIG>`

`bro eval status`

Summarize local exchange state

Usage: bro eval status [OPTIONS]

Flag	Description
`-c, --config <CONFIG>`

`bro optimize`

Advance or inspect history-driven routing optimization

Usage: bro optimize <COMMAND>

`bro optimize run`

Perform one deterministic controller transition from admitted Eval history

Usage: bro optimize run [OPTIONS]

Flag	Description
`--policy <POLICY>`	[default: auto]
`--candidate-tier <CANDIDATE_TIER>`	Challenger tier; defaults to the policy's adequacy explore tier
`--exploration-ppm <EXPLORATION_PPM>`	[default: 100000]
`--minimum-tasks <MINIMUM_TASKS>`	[default: 3]
`--maximum-tasks <MAXIMUM_TASKS>`	[default: 20]
`--minimum-pass-rate-ppm <MINIMUM_PASS_RATE_PPM>`	[default: 900000]
`--evaluator-config-digest <EVALUATOR_CONFIG_DIGEST>`
`-c, --config <CONFIG>`	[default: bitrouter.yaml]
`--socket <SOCKET>`

`bro optimize status`

Inspect the current controller state without changing files or the database

Usage: bro optimize status [OPTIONS]

Flag	Description
`--policy <POLICY>`	[default: auto]
`-c, --config <CONFIG>`	[default: bitrouter.yaml]

`bro trajectory`

Inspect, replay, and retain durable trajectory history in the local database

Usage: bro trajectory [OPTIONS] <COMMAND>

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. Uses the standard config resolution chain when omitted

`bro trajectory inspect`

Inspect one episode's structural health, route intents, and event digests

Usage: bro trajectory inspect [OPTIONS] <EPISODE_ID>

Argument	Description
`<EPISODE_ID>`	Globally unique trajectory episode id

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. Uses the standard config resolution chain when omitted

`bro trajectory replay`

Verify one episode and compare persisted live checkpoint evidence with replay

Usage: bro trajectory replay [OPTIONS] <EPISODE_ID>

Argument	Description
`<EPISODE_ID>`	Globally unique trajectory episode id

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. Uses the standard config resolution chain when omitted

`bro trajectory prune`

Prune delivered outbox rows and retention-expired terminal episodes

Usage: bro trajectory prune [OPTIONS] --before <BEFORE>

Flag	Description
`--before <BEFORE>`	Exclusive RFC3339 cutoff
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. Uses the standard config resolution chain when omitted
`--dry-run`	Report exact eligible counts without mutating the database

Cloud

bro cloud login either runs the RFC 8628 Device Authorization Grant or stores an existing BitRouter API key. Both credential types live under $XDG_DATA_HOME/bitrouter/account-credentials.json (mode 0600 on Unix). The API-key form performs no network request, which makes it suitable for CI. Interactive OAuth lets you pick the workspace this session is bound to; tokens refresh automatically within 60 s of expiry.

The default scope set covers inference:invoke, usage:read, keys:read/keys:write, billing:read, policy:read/policy:write, byok:read/byok:write, and namespace:read. Sensitive scopes such as billing:write are opt-in via --scope. After either login form, the bitrouter provider auto-enables in zero-config mode — every model your account is entitled to is routable as bitrouter:<model-id>.

Every leaf accepts --json for raw output; the default is a systemctl-style key:value block for single resources and a small table for lists. When the server returns 403 missing required scope: <s>, OAuth users get a copy-pasteable re-login hint; API-key users are told to mint a key with that scope.

`bro cloud`

Manage your BitRouter Cloud account — sign in/out, namespaces, keys, usage, requests, billing, policies, budgets, presets, and BYOK. Start with cloud login

Usage: bro cloud <COMMAND>

`bro cloud whoami`

Print the cloud identity stored on this machine alongside the /v1/* base URL the CLI will target

Usage: bro cloud whoami

`bro cloud api`

Make an authenticated request to a relative BitRouter Cloud API endpoint

Usage: bro cloud api [OPTIONS] <ENDPOINT>

Argument	Description
`<ENDPOINT>`	Relative API endpoint, for example `/v1/models`

Flag	Description
`-X, --method <METHOD>`	HTTP method. Defaults to GET, or POST when fields/input are present
`-H, --header <KEY:VALUE>`	Add an HTTP request header. May be repeated
`-f, --raw-field <KEY=VALUE>`	Add a string field to the JSON body or query string. May be repeated
`-F, --field <KEY=VALUE>`	Add a typed field to the JSON body or query string. May be repeated
`--input <FILE>`	Read the exact request body from a file, or `-` for stdin
`-i, --include`	Include the response status line and headers in stdout
`--silent`	Suppress the response body
`--verbose`	Print redacted request and response details to stderr

Modeled after gh api: injects the stored bearer against the logged-in origin and streams the response. Absolute URLs and redirect following are rejected, so the credential never leaves its login origin.

bro cloud api /v1/models
bro cloud api /v1/chat/completions --input request.json
bro cloud api /v1/responses -f model=openai/gpt-5 -F stream=true

Sign in to BitRouter Cloud from this terminal. Prints a verification URL — open it, approve, and this CLI stores an access token it refreshes automatically. This is the same credential the built-in bitrouter provider uses for inference, so providers login bitrouter is an alias for this command.

Usage: bro cloud login [OPTIONS]

Flag	Description
`--oauth-as <URL>`	Authorization server URL. Defaults to <https://api.bitrouter.ai>; override only for a self-hosted deployment (env: BITROUTER_OAUTH_AS)
`--client-id <ID>`	OAuth client id. Defaults to `bitrouter-cli`; override only for a self-hosted deployment (env: BITROUTER_OAUTH_CLIENT_ID)
`--scope <SCOPE>`	Permissions to request, as a space-delimited list. Defaults to a broad "developer" set; pass a narrower or wider list to override (env: BITROUTER_OAUTH_SCOPE)
`--api-key <BRK_API_KEY>`	Authenticate with a BitRouter API key instead of OAuth. Intended for CI and other non-interactive environments

bro cloud login                              # device flow, pick a workspace
bro cloud login --api-key "$BITROUTER_API_KEY"   # CI: no network, no browser

`bro cloud logout`

Sign out: revoke the stored token at the server (best-effort) and delete the local credentials file

Usage: bro cloud logout [OPTIONS]

Flag	Description
`--oauth-as <URL>`	Override the authorization server URL recorded in the credentials file for the revocation call
`--client-id <ID>`	Override the recorded OAuth client id for the revocation call

`bro cloud namespace`

Inspect the namespaces you own and the one this CLI is bound to

Usage: bro cloud namespace <COMMAND>

`bro cloud namespace list`

List the namespaces you own. The one this CLI is signed in to is marked (active). Switching namespaces is a re-login: bro cloud login and pick a different namespace in the browser

Usage: bro cloud namespace list [OPTIONS]

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud namespace current`

Print the namespace this CLI's credential is bound to. Offline — reads the local credential, no network call

Usage: bro cloud namespace current [OPTIONS]

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud keys`

Manage brk_ API keys in your namespace

Usage: bro cloud keys <COMMAND>

`bro cloud keys list`

List API keys on your account

Usage: bro cloud keys list [OPTIONS]

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud keys mint`

Mint a new API key. The plaintext is printed once

Usage: bro cloud keys mint [OPTIONS] --name <NAME>

Flag	Description
`--name <NAME>`	Operator-supplied display name
`--scope <SCOPE>`	Wire-format scope tokens (repeat the flag, or pass a single space-delimited list). Must be a subset of your effective scopes
`--expires-at <EXPIRES_AT>`	Optional expiry (RFC 3339, e.g. `2026-12-31T00:00:00Z`)
`--json`	Print the response as raw JSON instead of the human-readable summary

Returns the plaintext brk_… token exactly once — the server keeps only the SHA-256 hash. Requested scopes must be a subset of your effective scopes.

bro cloud keys mint --name ci --scope "policy:read usage:read"

`bro cloud keys revoke`

Revoke a key by id

Usage: bro cloud keys revoke [OPTIONS] <ID>

Argument	Description
`<ID>`	The key id (e.g. `k_…`)

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud usage`

Read aggregate spend / token counts for your account

Usage: bro cloud usage [OPTIONS]

Flag	Description
`--from <FROM>`	Lower bound (RFC 3339). Defaults to `to - 30 days`
`--to <TO>`	Upper bound (RFC 3339). Defaults to now
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud requests`

Page through recent inference requests

Usage: bro cloud requests [OPTIONS]

Flag	Description
`--limit <LIMIT>`	Page size (server clamps to `[1, 100]`)
`--offset <OFFSET>`	Offset into the result set
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud billing`

Credit balance and Stripe checkout

Usage: bro cloud billing <COMMAND>

`bro cloud billing balance`

Show the account's credit balance

Usage: bro cloud billing balance [OPTIONS]

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud billing checkout`

Start a Stripe checkout session for a credit top-up. Requires the billing:write scope

Usage: bro cloud billing checkout [OPTIONS] --amount-cents <AMOUNT_CENTS>

Flag	Description
`--amount-cents <AMOUNT_CENTS>`	Amount in USD cents
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy`

Generic CRUD over the typed policy registry

Usage: bro cloud policy <COMMAND>

--spec reads a JSON file (or - for stdin) holding the flat inner spec body — e.g. {"window": "day", "limit_micro_usd": 5000000} for a budget. effective and for-principal answer "what would happen to a request from this principal" without making an inference call. budget and preset are typed sugar over the same rows.

`bro cloud policy list`

List policies on your account

Usage: bro cloud policy list [OPTIONS]

Flag	Description
`--kind <KIND>`	Narrow the list to one kind [possible values: budget, rate-limit, guardrail, preset]
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy get`

Fetch one policy

Usage: bro cloud policy get [OPTIONS] <ID>

Argument	Description
`<ID>`	The resource id

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy create`

Create a policy. Spec body is read from --spec <file\|->

Usage: bro cloud policy create [OPTIONS] --name <NAME> --kind <KIND> --spec <SPEC>

Flag	Description
`--name <NAME>`	Operator-supplied display name
`--kind <KIND>`	Kind discriminator — selects which shape `--spec` must take [possible values: budget, rate-limit, guardrail, preset]
`--spec <SPEC>`	Path to a JSON file containing the flat inner spec body, or `-` to read from stdin
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy update`

Update a policy's name and / or spec

Usage: bro cloud policy update [OPTIONS] <ID>

Argument	Description
`<ID>`	The policy id

Flag	Description
`--name <NAME>`	New name. Omit to leave unchanged
`--spec <SPEC>`	New spec. Path to a JSON file or `-` for stdin. Omit to leave unchanged
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy delete`

Delete a policy

Usage: bro cloud policy delete [OPTIONS] <ID>

Argument	Description
`<ID>`	The resource id

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy bind`

Attach a policy to a principal

Usage: bro cloud policy bind [OPTIONS] --principal-type <PRINCIPAL_TYPE> --principal-id <PRINCIPAL_ID> <ID>

Argument	Description
`<ID>`	The policy id

Flag	Description
`--principal-type <PRINCIPAL_TYPE>`	Principal kind (`namespace`, `api_key`, `oauth_token`, `oauth_client`)
`--principal-id <PRINCIPAL_ID>`	Principal id — interpretation depends on `--principal-type`
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy unbind`

Detach one binding from a policy

Usage: bro cloud policy unbind [OPTIONS] <ID> <BINDING_ID>

Argument	Description
`<ID>`	The policy id
`<BINDING_ID>`	The binding id (from `cloud policy bindings <id>`)

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy disable`

Park a policy — the engine skips it at request time

Usage: bro cloud policy disable [OPTIONS] <ID>

Argument	Description
`<ID>`	The resource id

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy enable`

Re-enable a previously disabled policy

Usage: bro cloud policy enable [OPTIONS] <ID>

Argument	Description
`<ID>`	The resource id

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy bindings`

List the bindings of one policy

Usage: bro cloud policy bindings [OPTIONS] <ID>

Argument	Description
`<ID>`	The resource id

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy effective`

Preview the effective policy for a principal

Usage: bro cloud policy effective [OPTIONS] --principal-type <PRINCIPAL_TYPE> --principal-id <PRINCIPAL_ID>

Flag	Description
`--principal-type <PRINCIPAL_TYPE>`	Principal kind (`namespace`, `api_key`, `oauth_token`, `oauth_client`)
`--principal-id <PRINCIPAL_ID>`	Principal id
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud policy for-principal`

List every policy bound to a principal

Usage: bro cloud policy for-principal [OPTIONS] <PRINCIPAL_TYPE> <PRINCIPAL_ID>

Argument	Description
`<PRINCIPAL_TYPE>`	Principal kind
`<PRINCIPAL_ID>`	Principal id

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud budget`

Typed wrapper over budget-kind policies

Usage: bro cloud budget <COMMAND>

`bro cloud budget list`

List every budget on the account

Usage: bro cloud budget list [OPTIONS]

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud budget get`

Fetch one budget

Usage: bro cloud budget get [OPTIONS] <ID>

Argument	Description
`<ID>`	The resource id

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud budget create`

Create a budget

Usage: bro cloud budget create [OPTIONS] --name <NAME> --window <WINDOW> --limit-micro-usd <LIMIT_MICRO_USD>

Flag	Description
`--name <NAME>`	Display name
`--window <WINDOW>`	Rolling-spend window [possible values: day, month, total]
`--limit-micro-usd <LIMIT_MICRO_USD>`	Spend cap in micro-USD (must be strictly positive)
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud budget update`

Patch a budget's fields

Usage: bro cloud budget update [OPTIONS] <ID>

Argument	Description
`<ID>`	The budget id

Flag	Description
`--name <NAME>`	New name
`--window <WINDOW>`	New window [possible values: day, month, total]
`--limit-micro-usd <LIMIT_MICRO_USD>`	New cap (must be strictly positive when supplied)
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud budget delete`

Remove a budget

Usage: bro cloud budget delete [OPTIONS] <ID>

Argument	Description
`<ID>`	The resource id

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud preset`

Typed wrapper over preset-kind policies

Usage: bro cloud preset <COMMAND>

`bro cloud preset list`

List every preset on the account

Usage: bro cloud preset list [OPTIONS]

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud preset get`

Fetch one preset

Usage: bro cloud preset get [OPTIONS] <ID>

Argument	Description
`<ID>`	The resource id

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud preset create`

Create a preset. Each clause is supplied as a JSON file (or - for stdin)

Usage: bro cloud preset create [OPTIONS] --name <NAME>

Flag	Description
`--name <NAME>`	Display name
`--guardrail <GUARDRAIL>`	Optional guardrail clause (JSON file or `-`)
`--budget <BUDGET>`	Optional budget clause
`--rate-limit <RATE_LIMIT>`	Optional rate-limit clause
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud preset update`

Patch a preset's clauses. Use --clear-* to drop a clause

Usage: bro cloud preset update [OPTIONS] <ID>

Argument	Description
`<ID>`	The preset id

Flag	Description
`--name <NAME>`	New name
`--guardrail <GUARDRAIL>`	Replace the guardrail clause (JSON file or `-`)
`--budget <BUDGET>`	Replace the budget clause
`--rate-limit <RATE_LIMIT>`	Replace the rate-limit clause
`--clear-guardrail`	Drop the guardrail clause
`--clear-budget`	Drop the budget clause
`--clear-rate-limit`	Drop the rate-limit clause
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud preset delete`

Remove a preset

Usage: bro cloud preset delete [OPTIONS] <ID>

Argument	Description
`<ID>`	The resource id

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud byok`

Bring-your-own-key provider keys

Usage: bro cloud byok <COMMAND>

`bro cloud byok list`

List every BYOK row on the account

Usage: bro cloud byok list [OPTIONS]

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

`bro cloud byok set`

Upsert a BYOK row. Ciphertext must be sealed by the caller against the cloud's current X25519 public key

Usage: bro cloud byok set [OPTIONS] --provider <PROVIDER> --ciphertext-b64 <CIPHERTEXT_B64> --kek-id <KEK_ID> --key-prefix <KEY_PREFIX>

Flag	Description
`--provider <PROVIDER>`	Upstream provider id (e.g. `anthropic`)
`--ciphertext-b64 <CIPHERTEXT_B64>`	Base64-encoded sealed-box ciphertext
`--kek-id <KEK_ID>`	KEK id used to seal `--ciphertext-b64`. Must match the cloud's current `primary_kek_id`
`--key-prefix <KEY_PREFIX>`	Operator-visible prefix of the underlying plaintext
`--api-base <API_BASE>`	Override API base for the provider
`--json`	Print the response as raw JSON instead of the human-readable summary

Ciphertext must be sealed against the cloud's current X25519 public key before submission — the server only stores already-encrypted bytes. Fetch the current key from GET /v1/byok/encryption-pubkey first.

`bro cloud byok delete`

Remove a BYOK row by provider id

Usage: bro cloud byok delete [OPTIONS] <PROVIDER>

Argument	Description
`<PROVIDER>`	Provider id (the row's `provider_name`)

Flag	Description
`--json`	Print the response as raw JSON instead of the human-readable summary

Agents, ACP, and MCP

agents inspects ACP adapters, acp serve exposes one adapter over protocol-pure stdio, and mcp check verifies the upstream MCP servers declared in bitrouter.yaml. These are distinct directions: ACP connects a client to an agent; MCP connects BitRouter to upstream tools.

`bro agents`

Inspect ACP agent adapters, advertised capabilities, and configuration stubs

Usage: bro agents <COMMAND>

`bro agents list`

Show the bundled catalog of well-known agents and which of them are present under agents: in the loaded config. With --remote, also fetch and list the official ACP agent registry

Usage: bro agents list [OPTIONS]

Flag	Description
`--remote`	Also fetch the ACP agent registry (cdn.agentclientprotocol.com) and list its agents
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. When omitted, the binary resolves in this order: `./bitrouter.yaml` → `$BITROUTER_HOME/bitrouter.yaml` → `~/.bitrouter/bitrouter.yaml` → zero-config in-memory defaults (`bro init` is the explicit way to scaffold a file)
`--socket <SOCKET>`	Explicit local control socket for the daemon's accepted catalog

`bro agents inspect`

Inspect commands advertised by a fresh ACP session

Usage: bro agents inspect [OPTIONS] <AGENT>

Argument	Description
`<AGENT>`	ACP agent id or friendly alias

Flag	Description
`--direct`	Do NOT route this session's LLM traffic through the daemon — let the harness use its own provider auth. Routing is attempted by default when the harness supports headless redirection
`--base-url <BASE_URL>`	Override the gateway base URL (else derived from `server.listen`)
`--model <MODEL>`	Pin the harness's model (via its model env var / `-c model=`)
`--no-start`	Never auto-start a local daemon when none is running — fail fast
`--wait-ms <MS>`	How long to wait for the advertised command list [default: 2000]
`--source <SOURCE>`	Show only commands answered by one source Possible values:
`- bitrouter: BitRouter's own commands`
`- config:`	Prompt-expansion commands from the config
`- agent:`	Commands the agent advertises
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`

`bro agents check`

Spawn one agent, or every configured agent, and verify initialization

Usage: bro agents check [OPTIONS] [AGENT]

Argument	Description
`[AGENT]`	ACP agent id or friendly alias; omit to check configured agents

Flag	Description
`--direct`	Do NOT route this session's LLM traffic through the daemon — let the harness use its own provider auth. Routing is attempted by default when the harness supports headless redirection
`--base-url <BASE_URL>`	Override the gateway base URL (else derived from `server.listen`)
`--model <MODEL>`	Pin the harness's model (via its model env var / `-c model=`)
`--no-start`	Never auto-start a local daemon when none is running — fail fast
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. When omitted, the binary resolves in this order: `./bitrouter.yaml` → `$BITROUTER_HOME/bitrouter.yaml` → `~/.bitrouter/bitrouter.yaml` → zero-config in-memory defaults (`bro init` is the explicit way to scaffold a file)

bro agents check codex-acp

Spawns the adapter, performs ACP initialization, and reports whether the configured route is usable.

`bro agents conformance`

Run the ACP-compatibility suite against a catalog agent and print the conformance: block to record in its runtime entry. Needs no provider credentials: the agent is launched with its own routing pointed at an ephemeral loopback gateway that records what reached it. It does spawn the agent, so its package or binary must be installed.

Usage: bro agents conformance <ID>

Argument	Description
`<ID>`	Agent id, either `<runtime>/<harness>` or a bare harness id (`local/` is the default runtime and may be elided)

`bro agents scaffold`

Print a YAML stub for an agent (paste under agents: in bitrouter.yaml). Resolves from the bundled catalog first, then the ACP registry (npx/uvx distributions only)

Usage: bro agents scaffold <ID>

Argument	Description
`<ID>`	Agent id (see `bro agents list` / `list --remote`)

`bro mcp`

Check configured upstream MCP servers

Usage: bro mcp <COMMAND>

`bro mcp check`

Connect, negotiate MCP capabilities, and list advertised tools

Usage: bro mcp check [OPTIONS] [SERVER]

Argument	Description
`[SERVER]`	Check only this configured server; omit to check all of them

Flag	Description
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`

bro mcp check
bro mcp check docs

Connects to one or every configured upstream, negotiates MCP capabilities, and lists the tools each server advertises.

`bro acp`

ACP client integration over stdio, plus compatibility commands. serve exposes an ACP-compatible adapter process over protocol-pure stdio.

Usage: bro acp <COMMAND>

`bro acp evolution`

Control checkpoint feedback and policy-block evolution on the local daemon

Usage: bro acp evolution [OPTIONS] <COMMAND>

Flag	Description
`-c, --config <CONFIG>`

`bro acp evolution status`

Inspect modes, blocks, scheduled checkpoints and judge task status

Usage: bro acp evolution status

`bro acp evolution mode`

Select feedback mode; automatic requires a configured judge model

Usage: bro acp evolution mode [OPTIONS] <MODE>

Argument	Description
`<MODE>`	[possible values: off, manual, automatic]

Flag	Description
`--judge-model <JUDGE_MODEL>`

`bro acp evolution register`

Usage: bro acp evolution register <FILE>

Argument	Description
`<FILE>`

`bro acp evolution revise`

Start the next experiment for the same block; retain the previous evidence

Usage: bro acp evolution revise --expected-experiment <EXPECTED_EXPERIMENT> <FILE>

Argument	Description
`<FILE>`

Flag	Description
`--expected-experiment <EXPECTED_EXPERIMENT>`

`bro acp evolution restore`

Withdraw the current candidate and return to its supported baseline

Usage: bro acp evolution restore --expected-experiment <EXPECTED_EXPERIMENT> --expected-revision <EXPECTED_REVISION> --reason <REASON> <BLOCK>

Argument	Description
`<BLOCK>`

Flag	Description
`--expected-experiment <EXPECTED_EXPERIMENT>`
`--expected-revision <EXPECTED_REVISION>`
`--reason <REASON>`

`bro acp evolution learning`

Inspect the current evidence and proposed allocation without publishing

Usage: bro acp evolution learning [OPTIONS] <BLOCK>

Argument	Description
`<BLOCK>`

Flag	Description
`--experiment <EXPERIMENT>`

`bro acp evolution improve`

Reconcile current evidence against live routes and publish an eligible change

Usage: bro acp evolution improve [OPTIONS] <BLOCK>

Argument	Description
`<BLOCK>`

Flag	Description
`--experiment <EXPERIMENT>`

`bro acp checkpoints`

Freeze and evaluate already recorded native-session prefixes locally

Usage: bro acp checkpoints [OPTIONS] --agent <AGENT> <SESSION> <COMMAND>

Argument	Description
`<SESSION>`

Flag	Description
`--agent <AGENT>`
`-c, --config <CONFIG>`

`bro acp checkpoints judge`

Judge an existing checkpoint with an explicitly selected configured model

Usage: bro acp checkpoints --agent <AGENT> <SESSION> judge --model <MODEL> <CHECKPOINT>

Argument	Description
`<CHECKPOINT>`

Flag	Description
`--model <MODEL>`

`bro acp checkpoints judge-job`

Inspect a durable judge job, or resume it with its recorded input and model

Usage: bro acp checkpoints --agent <AGENT> <SESSION> judge-job [OPTIONS] <JOB_ID>

Argument	Description
`<JOB_ID>`

Flag	Description
`--resume`

`bro acp checkpoints rubric`

Prepare or submit evidence-grounded rubric scores from recorded content

Usage: bro acp checkpoints --agent <AGENT> <SESSION> rubric <COMMAND>

`bro acp checkpoints rubric prepare`

Export the fixed rubric library and cited evidence for a frozen checkpoint

Usage: bro acp checkpoints rubric prepare <CHECKPOINT>

Argument	Description
`<CHECKPOINT>`

`bro acp checkpoints rubric submit`

Validate and store a structured rubric revision without invoking a model

Usage: bro acp checkpoints rubric submit <FILE>

Argument	Description
`<FILE>`

`bro acp checkpoints create`

Freeze exactly the currently observed prefix; rejects a stale watermark

Usage: bro acp checkpoints --agent <AGENT> <SESSION> create --watermark <WATERMARK>

Flag	Description
`--watermark <WATERMARK>`

`bro acp checkpoints list`

List immutable prefixes for this native session

Usage: bro acp checkpoints --agent <AGENT> <SESSION> list

`bro acp checkpoints show`

Read the original content versions referenced by a checkpoint

Usage: bro acp checkpoints --agent <AGENT> <SESSION> show <CHECKPOINT>

Argument	Description
`<CHECKPOINT>`

`bro acp checkpoints resources`

Inspect resource snapshots, or refresh them from existing local records

Usage: bro acp checkpoints --agent <AGENT> <SESSION> resources [OPTIONS] <CHECKPOINT>

Argument	Description
`<CHECKPOINT>`

Flag	Description
`--refresh`

`bro acp checkpoints submit`

Import an idempotent assessment revision or explicit retraction from JSON

Usage: bro acp checkpoints --agent <AGENT> <SESSION> submit <FILE>

Argument	Description
`<FILE>`

`bro acp checkpoints history`

Read immutable assessment revisions and their selection decisions

Usage: bro acp checkpoints --agent <AGENT> <SESSION> history

`bro acp checkpoints effective`

Inspect the selected assessment, including unassessed appends

Usage: bro acp checkpoints --agent <AGENT> <SESSION> effective

`bro acp checkpoints family`

Inspect related native forks with a union of observed request costs

Usage: bro acp checkpoints --agent <AGENT> <SESSION> family

`bro acp recordings`

Inspect or delete locally recorded ACP conversation content

Usage: bro acp recordings [OPTIONS] <COMMAND>

Flag	Description
`-c, --config <CONFIG>`	Config selecting the local content database

`bro acp recordings list`

List recorded native sessions under a configured agent source

Usage: bro acp recordings list --agent <AGENT>

Flag	Description
`--agent <AGENT>`

`bro acp recordings show`

Export canonical events, replay audit, gaps, and observed request links

Usage: bro acp recordings show --agent <AGENT> <SESSION>

Argument	Description
`<SESSION>`

Flag	Description
`--agent <AGENT>`

`bro acp recordings delete`

Delete this session's locally captured content

Usage: bro acp recordings delete --agent <AGENT> <SESSION>

Argument	Description
`<SESSION>`

Flag	Description
`--agent <AGENT>`

`bro acp serve`

Expose an ACP-compatible agent adapter over stdio for an ACP client

Usage: bro acp serve <AGENT> [OPTIONS]

Argument	Description
`[AGENT]`	Agent id — a bundled-catalog id (`claude-acp`, `codex-acp`, `gemini-cli`, `opencode`, `pi-acp`, `hermes-acp`, `openclaw`) or an entry under `agents:` in the config. A catalog id needs no config entry; `bro agents check <agent>` previews whether it will route or run direct

Flag	Description
`--turn-timeout <SECS>`	Per-turn deadline in seconds. On elapse the agent is asked to cancel cooperatively; a turn that still doesn't finish errors
`--direct`	Do NOT route this session's LLM traffic through the daemon — let the harness use its own provider auth. Routing is attempted by default when the harness supports headless redirection
`--base-url <BASE_URL>`	Override the gateway base URL (else derived from `server.listen`)
`--model <MODEL>`	Pin the harness's model (via its model env var / `-c model=`)
`--no-start`	Never auto-start a local daemon when none is running — fail fast
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`. Resolves via the standard chain when omitted: `./bitrouter.yaml` → `$BITROUTER_HOME` → `~/.bitrouter/bitrouter.yaml` → zero-config defaults

bro acp serve codex-acp

Exposes the selected adapter over stdio for an ACP client. It preserves the selected harness's session semantics; it does not create a durable BitRouter workflow.

Skills

bro skills inspects installed Agent Skills and scaffolds a local SKILL.md. Installing a published skill remains the responsibility of the agent runtime or its skill installer; BitRouter no longer exposes an origin MCP server that installs skills for a client.

`bro skills`

Inspect installed Agent Skills and scaffold a local SKILL.md

Usage: bro skills <COMMAND>

`bro skills list`

List installed skills

Usage: bro skills list [OPTIONS]

Flag	Description
`-g, --global`	Operate on the global skills directory (`~/.claude/skills/`)

bro skills list
bro skills list --global

`bro skills init`

Scaffold a new SKILL.md in the current directory

Usage: bro skills init [OPTIONS] <NAME>

Argument	Description
`<NAME>`	Skill name written into the generated frontmatter

Flag	Description
`-o, --output <OUTPUT>`	Output path for the SKILL.md (default: `<NAME>/SKILL.md`)

bro skills init my-skill

This creates my-skill/SKILL.md in the current directory unless --output names another path.

Coding agents

Choose the interaction model that matches the task:

bro launch, bro claude, and bro codex preserve the harness's native interface.
bro code opens BitRouter's coding conversation and connects to an ACP agent.
bro run sends one ACP prompt headlessly and returns NDJSON, text, or only the final answer.

These commands do not imply the durable multi-attempt workflow described in BitRouter's architecture proposals. They run or connect to the selected harness using the released ACP and launch surfaces.

`bro launch`

Launch a coding-agent harness as an interactive native-TUI child. Routed harnesses are pointed at the local BitRouter daemon; own-auth harnesses launch directly and are not redirected. The human drives the harness's own TUI directly (use bro run for a headless ACP prompt). Follows cargo run's separator convention: bitrouter options come before --, everything after -- is forwarded to the agent verbatim, e.g. bro launch codex -- --search. Harnesses that route by env/args (claude, codex) are launched without touching any config file. Those that route by synthesized config (opencode, pi, hermes, openclaw) get it under .bitrouter/launch/ — your own agent config is still never modified. The agent authenticates to BitRouter with BITROUTER_API_KEY when it is set; otherwise a local placeholder is used (fine under the skip_auth default written by bro init). A missing claude / codex binary is offered for install via its official native installer; other harnesses report their own install command instead.

Usage: bro launch <AGENT> [OPTIONS] [-- <AGENT_ARGS>...]

Argument	Description
`[AGENT]`	Which agent harness to launch: any catalog harness with an interactive binary (`claude`, `codex`, `opencode`, `pi`, `hermes`, `openclaw`, `grok`, or `agy`; catalog ids such as `claude-acp`, `codex-acp`, `pi-acp`, and `hermes-acp` also resolve). Own-auth harnesses such as `grok` and `agy` launch direct and are not redirected
`[AGENT_ARGS]...`	Arguments forwarded verbatim to the native harness

Flag	Description
`--model <ID>`	Pin the harness's model to a daemon-routable id
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`
`--base-url <BASE_URL>`	Override the BitRouter inference base URL
`--no-install`	Fail instead of offering to install a missing supported harness
`--no-start`	Do not auto-start a missing local daemon
`--check`	Verify the executable, endpoint, and route without launching

bro launch claude

Routed harnesses point their model traffic at the local daemon. Own-auth harnesses launch directly. Use --check to verify the executable, endpoint, and route without starting the harness.

`bro claude`

Launch Claude Code's native interface through BitRouter

Usage: bro claude [OPTIONS] [-- <AGENT_ARGS>...]

Argument	Description
`[AGENT_ARGS]...`	Arguments forwarded verbatim to the native harness

Flag	Description
`--model <ID>`	Pin the harness's model to a daemon-routable id
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`
`--base-url <BASE_URL>`	Override the BitRouter inference base URL
`--no-install`	Fail instead of offering to install a missing supported harness
`--no-start`	Do not auto-start a missing local daemon
`--check`	Verify the executable, endpoint, and route without launching

`bro claude-code`

Alias for bro claude

Usage: bro claude-code [OPTIONS] [-- <AGENT_ARGS>...]

Argument	Description
`[AGENT_ARGS]...`	Arguments forwarded verbatim to the native harness

Flag	Description
`--model <ID>`	Pin the harness's model to a daemon-routable id
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`
`--base-url <BASE_URL>`	Override the BitRouter inference base URL
`--no-install`	Fail instead of offering to install a missing supported harness
`--no-start`	Do not auto-start a missing local daemon
`--check`	Verify the executable, endpoint, and route without launching

`bro codex`

Launch Codex's native interface through BitRouter

Usage: bro codex [OPTIONS] [-- <AGENT_ARGS>...]

Argument	Description
`[AGENT_ARGS]...`	Arguments forwarded verbatim to the native harness

Flag	Description
`--model <ID>`	Pin the harness's model to a daemon-routable id
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`
`--base-url <BASE_URL>`	Override the BitRouter inference base URL
`--no-install`	Fail instead of offering to install a missing supported harness
`--no-start`	Do not auto-start a missing local daemon
`--check`	Verify the executable, endpoint, and route without launching

`bro run`

Run one ACP agent prompt headlessly. Streams NDJSON by default, or text / quiet output when selected explicitly

Usage: bro run [OPTIONS] <AGENT> [PROMPT]

Argument	Description
`<AGENT>`	ACP agent id from the bundled catalog or `agents:` config
`[PROMPT]`	Prompt to send. Use `-` to read stdin

Flag	Description
`--prompt-file <PATH>`	Read the prompt from a file
`--load <NATIVE_SESSION_ID>`	Load a harness-native session and replay its history
`--resume <NATIVE_SESSION_ID>`	Resume a harness-native session without replaying history
`--cwd <PATH>`	Working directory supplied to the agent session
`--direct`	Do NOT route this session's LLM traffic through the daemon — let the harness use its own provider auth. Routing is attempted by default when the harness supports headless redirection
`--base-url <BASE_URL>`	Override the gateway base URL (else derived from `server.listen`)
`--model <MODEL>`	Pin the harness's model (via its model env var / `-c model=`)
`--no-start`	Never auto-start a local daemon when none is running — fail fast
`--turn-timeout <SECS>`	Per-turn deadline in seconds
`--result-schema <JSON\|@PATH>`	JSON Schema — inline JSON or `@path` — required of the final reply
`--approve-all`	Approve every permission request the harness makes
`--approve-reads`	Approve tool calls the harness labels `read` or `search` (the ACP tool kind); deny everything else, including unlabelled calls
`--deny-all`	Deny every permission request. This is the default
`--permission-policy <JSON\|@PATH>`	Per-tool policy, inline JSON or `@path`: `{"autoApprove":[…],"autoDeny":[…],"defaultAction":"approve"\|"deny"}`. Entries match the ACP tool kind (`read`, `edit`, `execute`, …), the tool-call title, or its first word. `autoDeny` wins over `autoApprove`; an unmatched request uses `defaultAction`, else the mode flag
`--format <FORMAT>`	Output: `ndjson` (the default), `text` (the transcript as `code <agent>` prints it to a pipe), or `quiet` (assistant text only) Possible values:
`- ndjson: One self-describing JSON object per line`
`- text:`	The transcript as the piped `bro chat <agent>` compatibility path prints it
`- quiet:`	The assistant's text and nothing else [default: ndjson]
`-c, --config <CONFIG>`	Path to `bitrouter.yaml`

bro run codex-acp "Review the current diff" --format quiet

The default permission policy denies requests. Choose an explicit approval mode or pass a per-tool policy when the task needs tools.

`bro code`

Open BitRouter's coding conversation, or connect directly when an agent id is supplied

Usage: bro code [OPTIONS] [AGENT]

Argument	Description
`[AGENT]`	ACP agent id. Omit to choose an agent in the conversation

Flag	Description
`--load <NATIVE_SESSION_ID>`	Load a harness-native session and replay its history
`--resume <NATIVE_SESSION_ID>`	Resume a harness-native session without replaying history
`--turn-timeout <SECS>`	Per-turn deadline in seconds for an agent session
`--direct`	Do NOT route this session's LLM traffic through the daemon — let the harness use its own provider auth. Routing is attempted by default when the harness supports headless redirection
`--base-url <BASE_URL>`	Override the gateway base URL (else derived from `server.listen`)
`--model <MODEL>`	Pin the harness's model (via its model env var / `-c model=`)
`--no-start`	Never auto-start a local daemon when none is running — fail fast
`-c, --config <CONFIG>`	Path to `bitrouter.yaml` for a local Code session
`--socket <SOCKET>`	Explicit local control socket for read-only operations

bro code
bro code codex-acp --model openai/gpt-5

Omit the agent id to choose inside the conversation, or pass an ACP agent id directly. --load replays a native session; --resume resumes it without replaying history.

Key, workflow-state, and update

`bro key`

Virtual-key management

Usage: bro key <COMMAND>

`bro key sign`

Mint a new brvk_ virtual key for a user. v1 does not sign a JWT — it creates a DB-backed virtual key and prints the plaintext once

Usage: bro key sign [OPTIONS] --user <USER>

Flag	Description
`-u, --user <USER>`	The owning user id
`-d, --db <DB>`	Database URL — any backend sea-orm supports (`sqlite://…`, `postgres://…`, `mysql://…`) [default: sqlite://./bitrouter.db]
`--policy <POLICY>`	Optional policy id to bind to the key (the `policy_id` column)

Mints a virtual key bound to an access-control policy — the per-key guardrails surface (allowed models, budgets, rate limits), distinct from routing policies. See Guardrails.

bro key sign --user ci --policy nightly-cap

`bro workflow-state`

Workflow-state trace/replay utilities

Usage: bro workflow-state <COMMAND>

Internal benchmark tooling — the plumbing behind the published Terminal-Bench reports (trace capture, outcome bundling, reward feedback), not a production user surface. It's documented here only for completeness; you almost certainly don't need it.

`bro workflow-state classifier-bakeoff`

Evaluate a shadow task/role/progress/risk classifier without routing

Usage: bro workflow-state classifier-bakeoff [OPTIONS] --fixtures <FIXTURES> --output <OUTPUT>

Flag	Description
`--fixtures <FIXTURES>`	Directory tree containing frozen workflow-state fixture JSON files
`--submission <SUBMISSION>`	Optional candidate submission JSON. Omit to evaluate the compiled deterministic scorecard as an uncalibrated baseline
`--output <OUTPUT>`	Output path for the deterministic manifest and evaluation report

`bro workflow-state bundle`

Build a deterministic benchmark trace bundle

Usage: bro workflow-state bundle [OPTIONS] --run-label <RUN_LABEL> --traces <TRACES> --cloud-usage <CLOUD_USAGE> --output-dir <OUTPUT_DIR>

Flag	Description
`--run-label <RUN_LABEL>`	Run label stored in `run-artifact.json`
`--traces <TRACES>`	Daemon workflow trace JSONL
`--cloud-usage <CLOUD_USAGE>`	BitRouter Cloud usage snapshot JSONL
`--outcomes <OUTCOMES>`	Optional request-scoped benchmark outcome JSONL. Omit when task or episode outcomes will be submitted through the Eval Exchange
`--policy-decisions <POLICY_DECISIONS>`	Optional policy routing decision JSONL from BITROUTER_POLICY_DECISION_JSONL
`--output-dir <OUTPUT_DIR>`	Output directory for traces/cloud usage/outcomes/artifacts

`bro workflow-state metering-usage`

Export daemon metering rows as usage JSONL for benchmark bundles

Usage: bro workflow-state metering-usage [OPTIONS] --database-url <DATABASE_URL> --output <OUTPUT>

Flag	Description
`--database-url <DATABASE_URL>`	Database URL for the daemon metering DB, for example sqlite:///path/bitrouter.db
`--output <OUTPUT>`	Output usage JSONL path
`--impute-price <IMPUTE_PRICES>`	Impute charges as provider:model=uncached,cache_read,cache_write,output. Legacy input,output is accepted only for records with no cache usage
`--since <SINCE>`	Inclusive RFC3339 lower bound. Defaults to the current UTC month
`--until <UNTIL>`	Exclusive RFC3339 upper bound. Only used with --since; defaults to now

`bro workflow-state reliability-report`

Replay persisted provider reliability state into a deterministic JSON report

Usage: bro workflow-state reliability-report --database-url <DATABASE_URL> --config <CONFIG> --output <OUTPUT>

Flag	Description
`--database-url <DATABASE_URL>`	Database URL for the daemon policy DB
`--config <CONFIG>`	Frozen BitRouter config that defines the reliability thresholds
`--output <OUTPUT>`	Output JSON report path

`bro workflow-state policy-oracle`

Estimate policy cost coverage and savings without changing live routing

Usage: bro workflow-state policy-oracle --traces <TRACES> --cloud-usage <CLOUD_USAGE> --policy-lock <POLICY_LOCK> --policy <POLICY> --effective-cost-factor <EFFECTIVE_COST_FACTOR_PPM> --target-savings <TARGET_SAVINGS_PPM> --output <OUTPUT>

Flag	Description
`--traces <TRACES>`	Protocol-native daemon workflow trace JSONL from the baseline run
`--cloud-usage <CLOUD_USAGE>`	Request-settled usage JSONL for the same baseline run
`--policy-lock <POLICY_LOCK>`	Policy lock containing the candidate routes to replay
`--policy <POLICY>`	Named policy within the lock
`--effective-cost-factor <EFFECTIVE_COST_FACTOR_PPM>`	Candidate effective cost divided by baseline cost, including any expected token, retry, or turn inflation (for example 0.24)
`--target-savings <TARGET_SAVINGS_PPM>`	Desired end-to-end savings fraction. Repeat for multiple targets
`--output <OUTPUT>`	Output JSON report path

`bro workflow-state reconcile-metering`

Reconcile selected metering rows against request-scoped receipts

Usage: bro workflow-state reconcile-metering [OPTIONS] --database-url <DATABASE_URL> --request-id <REQUEST_IDS>

Flag	Description
`--database-url <DATABASE_URL>`	Database URL for the daemon metering DB
`--api-base <API_BASE>`	Inference API root ending in `/v1` [default: https://api.bitrouter.ai/v1]
`--api-key-env <API_KEY_ENV>`	Environment variable containing the inference key [default: BITROUTER_API_KEY]
`--credentials-file <CREDENTIALS_FILE>`	Protected BitRouter Cloud credential file containing a static API key. OAuth credentials are never refreshed for settlement
`--request-id <REQUEST_IDS>`	Exact request id to reconcile. Repeat for every selected row
`--price <PRICES>`	Frozen price as provider:model=uncached,cache_read,cache_write,output. Repeat a provider/model pair for alternative schedules; settlement accepts only one distinct candidate that reconstructs the receipt
`--max-attempts <MAX_ATTEMPTS>`	Maximum durable receipt fetches per request [default: 12]
`--poll-interval-ms <POLL_INTERVAL_MS>`	Delay between pending-receipt polls [default: 1000]

`bro workflow-state apply-reward-feedback`

Apply task rewards to cheap replacement transitions before the next round

Usage: bro workflow-state apply-reward-feedback --database-url <DATABASE_URL> --traces <TRACES> --cloud-usage <CLOUD_USAGE> --outcomes <OUTCOMES> --policy-decisions <POLICY_DECISIONS>

Flag	Description
`--database-url <DATABASE_URL>`	Database URL for the policy daemon DB, for example sqlite:///path/bitrouter.db
`--traces <TRACES>`	Daemon workflow trace JSONL for the just-finished benchmark group
`--cloud-usage <CLOUD_USAGE>`	Exact, reconciled usage JSONL for the same benchmark group
`--outcomes <OUTCOMES>`	Benchmark outcome JSONL for the just-finished benchmark group
`--policy-decisions <POLICY_DECISIONS>`	Policy routing decision JSONL from BITROUTER_POLICY_DECISION_JSONL

`bro update`

Update the installed bitrouter binary in place to the latest release. Follows prereleases by default while pre-1.0. For Homebrew / cargo install installs it prints the right upgrade command instead

Usage: bro update [OPTIONS]

Flag	Description
`--check`	Report whether a newer version exists, then exit without changing anything
`--tag <TAG>`	Update (or downgrade) to a specific release tag, e.g. `1.0.0-alpha.18`. Named `--tag` to avoid clashing with the global `--version` flag
`--stable`	Only consider stable (non-prerelease) releases
`--restart`	After a successful update, restart a running daemon so it serves the new binary
`-y, --yes`	Skip the confirmation prompt

bro update

Updates the installed binary in place to the latest release — follows prereleases by default while pre-1.0. Homebrew and cargo install builds update through their own package manager instead.