> See the full index of documentation pages at https://docs.zettabyte.com/llms.txt.

# Command reference

> The zb commands and global flags at a glance.

Source: https://docs.zettabyte.com/docs/cli/command-reference

Last updated: 2026-10-02

This page condenses the full generated reference into one view. Run any command with `--help` for its complete flags and examples.

## 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; defaults to `https://api.zettabytecloud.com` |
| `-o, --output table\|wide\|json` | output format (default table) |
| `--wide` | show all columns in list output (same as `-o wide`) |
| `-y, --yes` | skip confirmation prompts |
| `ZB_INFERENCE_KEY` | inference key override for `zb chat` |
| `ZB_NO_UPDATE_NOTICE` | suppress the new-version notice |
| `NO_COLOR` | disable color |
| `TERM=dumb` | disable animation as well as color |

## 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`) |
| `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 |
| `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) |