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:

{"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

yb run options

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.

Exit status

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.