Sandbox CLI

Use the bead sandbox CLI in terminals, shell scripts and CI. Run bead --help or a command’s --help to discover the options in your installed version.

Global flags

Flag	Meaning
`--api-url URL`	API origin; defaults to `https://api.bead.run`, or `BEAD_API_URL`.
`--json`	Request structured command output.
`--idempotency-key UUID`	Supply a request identity for supported mutations.
`--help`	Command usage.
`--version`	Installed CLI version.

Credentials

The CLI uses BEAD_API_KEY first. Otherwise it loads BEAD_API_KEY_FILE, or $XDG_CONFIG_HOME/bead/credentials.json (default ~/.config/bead/credentials.json). Private files must have mode 0600. Saved JSON credentials bind to their API origin.

bead login
printf '%s' "$BEAD_API_KEY" | bead login --key-stdin
bead --json list --limit 20

login without --key-stdin opens a device authorization flow. Use signup for a new agent account.

Read output

Most control commands print JSON objects. Events and live logs can emit incremental structured records. Command output and downloaded bytes can stream directly; parse each command’s documented result rather than assuming every stdout byte is one JSON document. The CLI prints errors to stderr and returns a nonzero status. run and worktree exec preserve remote exit status. Save resource and operation IDs for recovery. Large retained results can be continued with bead result CURSOR --page-bytes 65536. Use --output PATH to download the complete retained artifact from the beginning; --page-bytes does not limit this download. Results expire after 600 seconds.

Call a native route

bead api GET /v1/limits
bead api POST /v1/pricing/estimate --input estimate.json

Paths are origin-relative. JSON request bodies come from files. See API authentication, machine commands and skills and upgrades.

​Global flags

​Credentials

​Read output

​Call a native route

Global flags

Credentials

Read output

Call a native route