CLI

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 --helpnpm 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.

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.

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.