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

# Overview and install

> What the zb CLI is, the four workload kinds, and how to install and sign in.

Source: https://docs.zettabyte.com/docs/cli/overview

Last updated: 2026-10-02

`zb` runs GPU workloads on zCLOUD from your terminal. You manage workloads, not infrastructure. Four kinds cover everything you can run, so there are no pods, nodes, or namespaces to learn. You launch a workload, watch it, open a shell in it, and download the results. Every command is scriptable, and AI agents can drive the full surface.

> [!NOTE]
> **Before you start**
> You need a zCLOUD account with GPU quota assigned to it. Create the account on app.zettabytecloud.com (see the Get started section). `zb` launches onto resources your account already has. It cannot create accounts, purchase GPUs, or change billing. `zb gpus` shows your quota. For more capacity, talk to your zCLOUD contact.

If you know the zCLOUD console, the kinds map directly onto it. A `job` is a training task. A `dev` is a notebook (Jupyter or VSCode). A `serve` is an inference service. A `box` is a custom notebook that you open a shell in.

## The four kinds of workload

| Kind | What it is | Typical use |
| --- | --- | --- |
| `job` | a container that runs a command to completion, optionally distributed | training runs, batch processing, experiments |
| `dev` | a persistent notebook with an IDE (Jupyter or VSCode); its contract is a URL | browser-based development |
| `serve` | an always-on inference service with an OpenAI-compatible endpoint | serving models, custom runtimes |
| `box` | a persistent dev container running your image's own ENTRYPOINT; its contract is a shell | a GPU box you shell into, agent sandboxes |

## The commands that matter

Ten verbs cover almost every day. Everything else is detail on top of these.

| What you're doing | The commands |
| --- | --- |
| Zero to GPU | `zb auth login` · `zb box --gpu h100:1` · `zb launch -k job --gpu h100:1 --run '…' -w` |
| Training jobs | `zb launch train.yaml -w` · `zb status` · `zb logs -f NAME` · `zb down NAME` |
| Code up, results down | `--workdir .` (ship your directory) · `zb push` / `zb sync NAME` (update running code) · `zb pull NAME ./results --watch` |
| Datasets | `zb volume put data ./imagenet` · `zb volume import data hf://ORG/NAME` · `--volume data:/data` at launch |
| GPU boxes | `zb box --gpu h100:1` · `zb box NAME` (re-attach) · `zb down NAME` |
| A shell in anything | `zb shell NAME` (every kind, every pod: `--role`, `--replica`, `--pod` pick the target) · `zb exec NAME -- CMD` |
| Serving | `zb launch -k serve --model NAME --gpu h100:1` · `zb chat NAME "hello"` · `zb scale NAME 1:3` |
| Models and images | `zb model import hf://ORG/NAME` · `zb model upload DIR --name NAME` · `zb image import REF` |
| Debugging | `zb doctor NAME` (match known failures) · `zb top NAME` (are the GPUs busy?) · `zb events NAME` · `zb status NAME --wide` |
| Cost hygiene | `zb ttl NAME 8h` · `zb stop NAME` · `zb down NAME` (volume data persists) |
| Driving it with an agent | `zb docs -o json` · `-o json` on everything · `zb wait NAME --for SUCCEEDED` |

## Install the CLI

**macOS / Linux**

```bash
curl -fsSL https://get.zettabytecloud.com | sh
```

**Windows (PowerShell)**

```powershell
irm https://get.zettabytecloud.com/install.ps1 | iex
```

One line installs the CLI. On macOS and Linux (arm64 and amd64) it installs into `~/.local/bin`. Set `ZB_INSTALL_DIR` to change the destination. Append `-s -- v0.1` to pin a version. `zb version` prints the installed version.

## Staying current

`zb upgrade` updates the binary in place to the latest build. `zb upgrade v0.2` pins a version. `zb upgrade --check` only reports whether an update exists. No login is needed. When a newer build is available, `zb` mentions it at most once a day, and only in a terminal. Scripts and agents never see the notice. Set `ZB_NO_UPDATE_NOTICE` to turn it off entirely.

## Sign in

`zb auth login` signs in with the same account you use on app.zettabytecloud.com and keeps you signed in on that machine.

```bash
zb auth login              # account username and password
zb auth login --sso        # in a browser: GitHub, Google, Hugging Face, or Microsoft
zb auth whoami             # who am I, and is the API reachable?
zb auth logout             # sign out
```

Use `--sso` if you created your account with GitHub, Google, Hugging Face, or Microsoft. Those accounts have no password, so the username/password form can never work for them. Pick the provider with `--provider google` (default `github`). The browser does not have to be on the same machine, so `--sso` works over SSH. The CLI never stores passwords.

In non-interactive environments (CI, agents), set the `ZB_API_KEY` environment variable or pass `--api-key`. Set `ZB_BASE_URL` or `--base-url` only if you do not target the default `https://api.zettabytecloud.com`.

## Hugging Face token

Gated Hugging Face repos need an access token. Save it once with `zb auth hf set`. The input is hidden and verified against huggingface.co. `zb auth hf status` shows the token masked, and `zb auth hf rm` forgets it. `zb model import` and `zb volume import` then use the token automatically, with a notice on each use. `--no-hf-token` forces an anonymous download. `zb launch` never sends the token on its own. Opt in per launch with `--hf-token`. Prefer a fine-grained read-only token. For scripts, `zb auth hf set --from-env` reads `$HF_TOKEN`.

`zb docs` prints the links to this documentation site (`--open` opens it in a browser). The links include llms-full.txt, the complete CLI docs as one plain-text file for AI agents. Next stop: the Quickstart.