# Command line (`yb`) `yb` is the command-line tool that comes with the Python SDK. You can use it to check your key, list models, run a test session, and look up errors, without writing code. Use `--json` for scripts and agents: results and errors use the versioned format below, and progress stays on standard error. Without it, commands retain their terminal output: most results are JSON, while docs, help, setup instructions and logs use text. ## Scripts and agents Put `--json` before or after the command, for example `yb --json models --ready` or `yb models --ready --json`. A finite command writes one JSON record followed by a newline: ```json {"schema_version":1,"command":"models","type":"result","ok":true,"data":[],"error":null,"context":{"project_id":"example-project"}} ``` `schema_version` is the envelope version, currently 1. `command` is null when argument parsing cannot identify it. `data` holds the normal result or useful partial results; `error` is null on success. `context` contains available project, model, deployment, session, request, generation and idempotency identifiers. Missing identifiers are omitted. Consumers should tolerate additional fields and unknown error codes. On failure, `ok` is false and `error` contains `code`, `message`, `next_step`, `retry`, `source_retry`, `retryable`, `http_status` (possibly null) and `docs`. `source_retry` preserves the error reference's category; `retry` describes the next action in this CLI context. For example, an expired observation normally permits a next request, but `yb run` ends its batch and closes the session, so its advice reflects that closure. Unknown server codes are preserved with conservative, nonretryable guidance. `yb run` retains observed counts, timings, errors and known closure/charge fields even when a batch fails or is interrupted. `requests_sent` counts SDK calls begun, not proof of server receipt or billable completion. Unknown settlement fields stay null. Exit 75 describes a temporary failure; it does not mean it is safe to replay robot actions. For an ambiguous deployment request, inspect its state and reuse the returned `context.idempotency_key` with `--idempotency-key` for the same operation. The CLI does not automatically retry mutations. `yb logs DEPLOYMENT --follow --json` emits newline-delimited JSON (NDJSON): `type:"event"` records followed by one `type:"end"` record on an orderly finish, handled interruption or error while output remains writable. The terminal data includes `last_sequence` and `events_received`. Resume with `--after N` using the last event your consumer processed. A terminal deployment state triggers one final event read; this is not a promise that no later event can ever be written. Reading logs from a failed deployment can succeed: the end record then has `ok:true` and `deployment_status:"failed"`. Without `--follow`, JSON mode returns one result containing an `events` list. Forced process termination or an unwritable output stream cannot provide an end record. Help uses `type:"help"` with `data.text`; docs use `type:"result"` with `data.markdown`. Both remain available without a project key. `yb setup --json` never prompts or writes to a keyring: it uses `YB_API_KEY` or one piped input line, reports verified project/origin and `stored:false`, and fails usefully when input is absent. Human `yb setup` retains its interactive keyring consent. `yb doctor --json` keeps its findings under `data` and returns `diagnostic_findings` with exit 1 when changes are needed. ## Everyday commands | Command | What it does | |---|---| | `yb setup [--url URL] [--no-keyring]` | Asks for your key without showing it, checks it, and can save it in your system keyring. It writes only its own entry, and asks before replacing a saved key. Outside a terminal, it reads the key from standard input. | | `yb models [--ready]` | With `--ready`, offered models and their connection state. An on-demand model may be idle until you connect. Without it, every model in the catalog. | | `yb run [--model M] [--requests N] [--max-spend-usd S]` | Runs a short test session: sends observations, prints each answer's timing and the cost, then closes. | | `yb sessions` | Your project's sessions, with state, completed requests and cost. | | `yb close ` | Closes a session. Safe to repeat. The model keeps running. | | `yb usage` | Your credit balance, credit reserved by open sessions, and your ledger. | | `yb docs [page] [--url URL]` | Lists the docs pages, or prints one as markdown. No key needed. | | `yb errors [code]` | Explains an error code without going online, or lists every code. When a code also names a way a session can end, such as `expired`, it explains both. No key needed. | | `yb doctor [--seconds N] [--url URL]` | Checks what slows your robot's link: Wi-Fi power saving, the Wi-Fi band and signal, and the round trip to your router compared with the service. It prints what to fix, and exits with 1 if it found something. It changes no settings. No key needed. | ## `yb run` options | Option | Default | Meaning | |---|---|---| | `--model` | `transport-demo` | The model to call. The default is the free sandbox; for a DROID robot, use `transport-demo-droid`. | | `--instruction` | `transport test` | The task, in words. | | `--requests` | 10 | How many observations to send. | | `--interval-ms` | 100 | Milliseconds between observations. | | `--budget-ms` | 2000 | The deadline for each answer (`max_action_age_ms`), in milliseconds. | | `--max-spend-usd` | `0` | The most the session may cost. | | `--transport` | `sync` | `owned` makes every network wait give up at the deadline. Use it on a real robot. | | `--fixture` | none | Recorded input: an `.npz` file with `image`, `wrist_image`, `state` and `prompt`. This loader supports the LIBERO schema. Mutually exclusive with `--example`. | | `--example` | off | Replay the recorded LIBERO frame bundled with the SDK; supports `pi05-libero` and `transport-demo`. | With the default, `transport-demo` (a free sandbox that returns placeholder actions), `yb run` generates placeholder data. A learned LIBERO model needs `--fixture` or `--example`; placeholder images are not meaningful task inputs. It also needs `--max-spend-usd`, such as `1`, because the default, `0`, works only on the free sandbox. ## Operator and developer commands These commands manage a private model server that one project owns, started and stopped on request. You don't need them to connect to the offered models. | Command | What it does | |---|---| | `yb deploy [--model M] [--minutes N] [--wait] [--region R]` | Starts a private model server. | | `yb list` | Lists the project's private model servers. | | `yb status ` | Shows one of them. | | `yb stop ` | Stops it. | | `yb logs [--follow] [--after N]` | Prints events after sequence N (default 0); JSON follow mode uses NDJSON. | | `yb diagnose ` | Measures the network delay to it, not the model's time. | | `yb demo ` | Sends one placeholder observation to a test server. | | `yb regions [--model M]` | Measures the network delay to each region. | ## Exit status | Status | Meaning | |---|---| | 0 | Success. | | 1 | An error or actionable diagnostic findings. JSON mode returns the error envelope on stdout; terminal mode uses stderr for errors. | | 2 | The command line was wrong. | | 75 | A temporary error, such as a full model. Retry later, and wait longer each time. | | 130 | The command was interrupted. Inspect any returned operation IDs and partial data before retrying. | ## Environment `yb` reads the same variables as the SDK: `YB_URL`, `YB_API_KEY`, `YB_PROJECT_ID` and `YB_ALLOW_INSECURE_HTTP`. See [Python SDK](https://yellowandblack.dev/docs/python-sdk.md#environment-variables).