> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox CLI

> Configure the sandbox CLI with global flags, API origins, and credentials, then discover commands and read JSON output.

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.

```bash theme={null}
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](https://docs.bead.run/agent-signup.md) 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

```bash theme={null}
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](https://docs.bead.run/api-reference/authentication.md), [machine commands](https://docs.bead.run/cli/machines.md) and [skills and upgrades](https://docs.bead.run/cli/skills-upgrades.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.