Scripting and agents
The machine contract, and how to hand the whole CLI to an AI agent.
Let an AI drive it
Autonomous agents can drive `zb` end to end: launch, wait, collect, iterate. Every command is non-interactive by default. Machine output is stable. Some errors state the fix in plain English, such as when you are not logged in; others only name the problem. Blocking primitives replace polling loops.
Give the agent the docs first. The complete CLI documentation ships as one plain-text file. Fetch `https://docs.zettabyte.com/docs/zcloud/cli/llms-full.txt` and paste it into context (`zb docs -o json` returns the URLs). Then let the agent run `zb` directly. Set `ZB_API_KEY` in its environment and it never needs an interactive login.
# the loop an agent runs: every step blocks or returns stable JSON
zb launch train.yaml --name exp-1 -w -o json # blocks until RUNNING (straight through QUEUED)
zb wait exp-1 --for SUCCEEDED --timeout 4h # exit 1 on FAILED or timeout
zb pull exp-1 ./results # collect outputs
zb status -o json # read the world, decide the next launch
Non-interactive by design
- Confirmation prompts appear only on destructive commands, and only when stdin is a TTY. `-y` skips them. The interactive commands (`zb init`, `zb auth login`, `zb chat`, `zb shell`) prompt only on a TTY. Without one, nothing ever waits for input.
- Spinners, progress bars, status glyphs, and color render only when the stream is a terminal. Piped or redirected streams and `-o json` get plain, line-oriented output. Transient transfer progress degrades to occasional milestone lines on stderr. stdout stays the script-facing record.
- `NO_COLOR` disables color. `TERM=dumb` disables animation too.
Exit codes
| Code | Meaning |
|---|
| 0 | success |
| 1 | error, including an unknown command |
| 2 | usage error (a bad flag or the wrong number of arguments) |
| 3 | not found |
| 4 | ambiguous name |
| 130 | Ctrl-C at an interactive prompt (TTY only; scripts and agents never see it) |
`zb exec` is the exception: it returns the remote command's exit code.
JSON output
`-o json` prints stable machine output on stdout. On failure, a structured error also lands on stderr:
{ "error": { "type": "error", "message": "no workload named \"train-1\" — run `zb status` to see what's live" }, "exit_code": 3 }
`type` carries the server's error type when one exists, `error` otherwise. List rows carry `status` (normalized), `status_raw` (the server's own value), and `raw` (the full server row). The detail view's `-o json` carries `detail` plus `spec`, `runtime`, and `diagnosis` (state and summary) sections. In table mode, `zb status NAME` shows the identity block plus the next commands that make sense. It adds a plain-language Health line when something is wrong ("image can't be pulled", "container is crash-looping"). `--wide` adds the creation spec and live runtime even when healthy.
Workload statuses
The `status` field and table column use one normalized enum across kinds. Unrecognized server states pass through uppercased rather than being hidden.
| Status | Meaning |
|---|
| `QUEUED` | the launch is parked server-side waiting for GPU quota; the workload has not been created yet |
| `CREATING` | accepted; creation still in progress |
| `PENDING` | accepted, waiting to schedule |
| `STARTING` | scheduled, containers coming up |
| `RUNNING` | up |
| `STOPPED` | not running: a serve scaled to zero (dev and box can report it too) |
| `SUCCEEDED` | ran to completion |
| `FAILED` | ended in error |
| `TERMINATING` | being deleted |
| `MISSING` | the record exists but nothing is running behind it |
| `UNKNOWN` | the platform could not verify the workload on this request; the workload itself is most likely fine |
| `DELETED` | gone, but the name still resolves so `zb logs` and `zb pull` can reach outputs |
Queued rows carry `queue_position` (1-based, ordered by priority then submit time) and `queue_expires_at` in the row's `raw` JSON. A queued launch answers HTTP 202 with `queued: true`. `UNKNOWN` is deliberately not `FAILED`. Rows carry `status_unverified: true` so scripts can tell "unobservable" from "broken". Serve rows carry a `ready_status` tri-state for the same reason: `READY`, `LOADING`, or `UNVERIFIABLE`. `UNVERIFIABLE` means the readiness check could not run, which is not the same as still loading.
Blocking primitives and sweeps
- `zb launch -w` blocks until running. `zb wait NAME --for STATUS --timeout DURATION` exits 1 on `FAILED` or timeout. `zb logs -f` ends itself at a terminal state.
- `QUEUED` is non-terminal: `zb wait` (and `launch -w`) poll through a queued launch into `PENDING` and `RUNNING` with no extra handling.
- Sweeps: template one spec with `--set` plus `--name exp-N`. A name collision is a clean 4xx failure, never a silent duplicate. See Iterate and sweep on the Launch and specs page.
Next steps
[Command reference](https://docs.zettabyte.com/docs/zcloud/cli/command-reference): the zb commands and global flags at a glance.