Command reference
The zb commands and global flags at a glance.
Verified with zb v0.1.
This page lists the commands at a glance. Run any command with `--help` for its complete flags and examples. `zb docs` prints the links to the complete CLI documentation, including llms-full.txt, one plain-text file.
Global flags and environment
| Flag or variable | Meaning |
|---|
| `--api-key`, `ZB_API_KEY` | management API key; otherwise the stored login is used |
| `--base-url`, `ZB_BASE_URL` | API base URL; the flag overrides `ZB_BASE_URL` and the saved server |
| `-o, --output table|wide|json` | output format (default table) |
| `--wide` | show all columns in list output (same as `-o wide`) |
| `-y, --yes` | confirm destructive actions without prompting (required in non-interactive use) |
| `ZB_INFERENCE_KEY` | inference key override for `zb chat` |
Exit status
Exit codes for the common outcomes:
| Code | Meaning |
|---|
| 0 | success |
| 1 | failure: not signed in, an unknown command, or `zb wait` ending on `FAILED` or timing out |
| 2 | usage error: an unknown flag or the wrong number of arguments |
| 3 | the named workload was not found (`zb status` with an unknown name) |
| the remote code | `zb exec` returns the exit code of the command it ran |
With `-o json`, a failure also prints a JSON object on stderr that carries the same code in an `exit_code` field.
Workload lifecycle
| Command | What it does |
|---|
| `zb init` | create a workload spec file, step by step |
| `zb launch` | launch a workload from a spec file and/or flags |
| `zb status` | show all workloads, or one workload in detail (alias `st`) |
| `zb top` | show live GPU utilization and serving metrics (`-w` to watch) |
| `zb wait` | block until a workload reaches a status |
| `zb logs` | show a workload's logs (`-f` to follow) |
| `zb events` | show recent platform events for a workload |
| `zb describe` | show a workload's full configuration and runtime detail |
| `zb doctor` | diagnose a failing workload from its logs and events |
| `zb pods` | list a workload's pods (roles, replicas, nodes) |
| `zb down` | delete workloads, any kind (alias `rm`) |
Inside a workload
| Command | What it does |
|---|
| `zb shell` | open an interactive shell inside a workload |
| `zb exec` | run a one-off command in a workload and get its exit code |
| `zb cp` | copy a small file to or from a workload (one side is `NAME:/path`; the destination must be a full file path, not a directory) |
| `zb push` | copy a directory into a running workload |
| `zb sync` | sync a directory into a running workload (only changed files) |
| `zb pull` | download a workload's results (its outputs mount) |
| `zb url` | print a workload's endpoint (serve: OpenAI-compatible API; dev: IDE; boxes have none) |
| `zb chat` | talk to a serve workload (OpenAI chat completions) |
| `zb box` | create a dev container and shell in (one command, like `docker run -it`) |
Serve control and TTL
| Command | What it does |
|---|
| `zb stop` | stop a serve workload (scale to zero, keep everything else) |
| `zb start` | start a stopped serve workload |
| `zb scale` | set a serve workload's replica bounds |
| `zb ttl` | show, extend, or clear a workload's autoclean TTL (any kind) |
Models
| Command | What it does |
|---|
| `zb model upload` | upload a model directory and register it |
| `zb model import` | import a Hugging Face model (the platform downloads it for you) |
| `zb model register` | register weights that already exist, on the share volume (`--share-dir`), in your own bucket (`--from-s3`), or on a volume (`--volume`) |
| `zb model ls` | list models |
| `zb model get` | show a model (detail plus version status) |
| `zb model rm` | delete a model (`--purge` also deletes its weights) |
| `zb model tag add|rm|set|clear` | tag models to organize them (list with `--tag`) |
| `zb model fav`, `zb model unfav` | mark or unmark a model as a favorite (list with `--fav`) |
| `zb model note` | attach a free-text note to a model (no text clears it) |
Images
| Command | What it does |
|---|
| `zb image import` | mirror an external image into your private registry |
| `zb image build` | build a runtime image from a Dockerfile (or snapshot a pod) |
| `zb image ls` | list image import and build jobs (`--private` hides platform presets) |
| `zb image get` | show an image job's status |
| `zb image rm` | remove image job records (does not delete registry bytes) |
| `zb image cred add|ls|rm` | manage saved registry credentials for private imports |
| `zb image tag add|rm|set|clear` | tag images to organize them (not the docker version tag) |
| `zb image fav`, `zb image unfav` | mark or unmark an image as a favorite |
| `zb image note` | attach a free-text note to an image (no text clears it) |
Volumes and storage
| Command | What it does |
|---|
| `zb volume create` | create a volume (`--class` is required; `zb volume classes` lists the classes) |
| `zb volume ls` | list volumes (with the tenant storage quota) |
| `zb volume put` | copy a local directory onto a volume (datasets; big files resume automatically) |
| `zb volume import` | download a URL or `hf://` repo straight onto a volume, on the platform's bandwidth |
| `zb volume inspect` | look inside a volume (capacity, usage, top entries) |
| `zb volume expand` | expand a volume to a larger size |
| `zb volume rm` | delete a volume (its data is gone for good) |
| `zb volume classes` | list available storage classes |
| `zb s3 create|ls|rm|quota` | object-storage buckets you own (lifecycle only; use any S3 client for data) |
| `zb uploads ls`, `zb uploads cancel` | list or cancel large transfers still in flight |
Keys, account, and misc
| Command | What it does |
|---|
| `zb key create` | create an inference API key (the secret is shown only once) |
| `zb key ls` | list inference API keys |
| `zb key update` | update an inference API key (only the flags you set) |
| `zb key rm` | delete an inference API key |
| `zb auth login` | log in: username/password, or `--sso` in a browser (GitHub, Google, Hugging Face, Microsoft) |
| `zb auth logout` | sign out |
| `zb auth whoami` | show who you are and confirm the API is reachable |
| `zb auth hf set|status|rm` | save a Hugging Face token for gated downloads (stored locally, always shown masked) |
| `zb gpus` | show GPU types, availability, and quota |
| `zb docs` | print links to the hosted docs and the agent-facing llms-full.txt (`--open` for a browser) |
| `zb upgrade` | update the zb binary in place to the latest build (VERSION pins; `--check` only reports) |
| `zb version` | print the zb version |
| `zb completion` | generate the shell completion script (bash, zsh, fish, powershell) |
Next steps
- [Overview and install](https://docs.zettabyte.com/docs/zcloud/cli/overview): what the zb CLI is, the four workload kinds, and how to install and sign in.
- [Quickstart](https://docs.zettabyte.com/docs/zcloud/cli/quickstart): start a GPU shell with one command, then run a first job.
- [Everyday commands](https://docs.zettabyte.com/docs/zcloud/cli/everyday-commands): status, logs, shell, and exec for a running workload.