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

# CLI

The b3os command line for signing in, scraping, screenshots, sandboxes, routines, actions and the MCP server, built for scripts and agents too.

The CLI is the `b3os` package on npm, a Node program (Node 20.16 or later) built on the TypeScript SDK. Run it without installing, or install it globally:

```bash
npx b3os --help
npm install -g b3os
```

## Sign in

```bash
b3os login
```

`login` starts a device login: it prints a short code and a link to `https://beta.b3os.org/app/device`, and opens a browser when there is a terminal. Approve it there for one organization and project, with scopes no wider than your own, and the CLI receives a `b3os_pat_` token. It stores the token in `~/.config/b3os/credentials.json` (or under `$XDG_CONFIG_HOME`), readable only by you, and never prints it. `--scope` asks for fewer scopes.

The CLI uses `--api-key` first, then `B3OS_API_KEY`, then the stored token, so in CI you set `B3OS_API_KEY` and skip `login`. `b3os whoami` shows which credential is in use, with its organization, project and scopes. Inside a B3OS sandbox the CLI sends node operations to `B3OS_API_URL` and needs no key for them.

## Commands

| Command | Does |
|---|---|
| `login`, `logout`, `whoami` | Sign in, remove the stored token, show the credential in use |
| `keys list`, `create`, `get`, `update`, `revoke` | Manage API keys; `create` prints the secret once |
| `scrape <url>` | Scrape a page; Markdown on stdout by default, `--format` for others |
| `screenshot <url>` | Take a screenshot and save it with `--out`; `--frame`, `--background`, `--full-page`, `--selector` style it |
| `video <script.json>` | Record a video from a JSON script, follow its progress and save the MP4 |
| `sandbox create`, `exec`, `shell`, `ls`, `get`, `logs`, `url`, `rm` | Create sandboxes, run commands, open a terminal, follow background logs, mint a port URL, delete |
| `routine deploy <file>`, `run <routine>`, `logs <run_id>` | Publish a routine from YAML or JSON, start a run and print its output, follow a run's steps |
| `action search`, `describe`, `run` | Find, inspect and call marketplace actions |
| `mcp install --client claude`, `mcp serve` | Register the MCP server with a client, or run the stdio server in this process |
| `bench ping`, `bench scrape`, `bench exec` | Time calls from where you run it (below) |
| `api <METHOD> <path>` | Any operation, with `--data`, `--query` and `--header` |

`b3os <command> --help` shows each command's options. `sandbox exec <id> -- <command>` streams the output and exits with the command's own exit code, and `sandbox create --grant` gives the new sandbox an [API grant](/sandboxes/agents#grant-access).

## Built for scripts and agents

- `--json` prints machine-readable output; errors then go to stderr as `{"error": {code, status, title, detail, type, request_id, errors}}`.
- `--yes` answers confirmations. Without a terminal the CLI never prompts, and a destructive command without `--yes` exits with code 2.
- Every command also takes `--quiet`, `--api-key`, `--base-url` and `--timeout`.

Exit codes are stable:

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | An error not listed here |
| 2 | Usage error, or a confirmation refused without `--yes` |
| 3 | Authentication or authorization (`401`, `403`) |
| 4 | Not found (`404`) |
| 5 | Invalid request, conflict or wrong state (other `4xx`, `421 edge_only` included) |
| 6 | Rate limited, out of quota or out of credits (`429`, `402`) |
| 7 | Server error or unavailable (`5xx`) |
| 8 | Timeout |
| 9 | Connection error |
| 10 | A job or routine run failed, or a command was killed without an exit code |
| 130 | Interrupted |

`sandbox exec` and `sandbox shell` exit with the remote command's own code when it ran.

## MCP setup

`b3os mcp install --client claude` (or `cursor`, `codex`) adds an entry that runs the local server, `npx -y @b3os/mcp`. The server reads `B3OS_API_KEY` or your `login` token itself, so the client's configuration holds no secret. `--scope project` writes the project's configuration instead of your user's, `--packs github,slack` adds those packs' actions as tools, `--remote` points Claude or Cursor at the remote server with your key in an `Authorization` header (stored in the client's configuration), and `--print` shows the entry without writing it. See [MCP server](/sdks/mcp).

## Bench

`b3os bench ping -n 30` (also `scrape --url <url>` and `exec --sandbox <id>`) times calls in sequence from your machine and prints client-side p50, p95 and p99 next to the server's own `Server-Timing` total and phases, so you see how much of each call is network, TLS and the edge. It is a quick probe, not the published benchmark harness: its numbers are client side, from wherever you run it. `--interval-ms` spaces the calls to see latency after idle gaps, and `--json` prints every sample.