> 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/zcloud/cli/overview

Last updated: 2026-11-05

`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 namespaces to learn, and pods and nodes appear only in a few commands, such as `zb pods` and `--nodes`. You launch a workload, watch it, open a shell in it, and download the results.

Verified with zb v0.1.

> [!NOTE]
> **Before you start**
> You need a zCLOUD account with GPU quota assigned to it. Create the account on console.zettabyte.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` lists the GPU types available to the account and, where the platform reports it, quota and current usage. 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

A handful of verbs cover almost every day. Everything else is detail on top of these. `TYPE:COUNT` stands for a GPU type listed by `zb gpus` and a card count.

| What you're doing | The commands |
| --- | --- |
| Zero to GPU | `zb auth login` · `zb box dev1 --image pytorch --gpu TYPE:COUNT` · `zb launch -k job --gpu TYPE:COUNT --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 NAME --image pytorch --gpu TYPE:COUNT` · `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 TYPE:COUNT` · `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 the commands that print data (`zb docs` and `zb config` do; `zb version` prints plain text) · `zb wait NAME --for SUCCEEDED` |

## Install the CLI

**macOS / Linux**

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

**Windows (PowerShell)**

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

One line installs the CLI. On macOS and Linux (arm64 and amd64) it installs into `~/.local/bin`. If `zb` is reported as not found afterwards, add `~/.local/bin` to `PATH`. 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 VERSION` pins a version. `zb upgrade --check` only reports whether an update exists. No login is needed.

## Sign in

`zb auth login` signs in with the same account you use on console.zettabyte.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 to target a server other than the one the CLI already uses (`zb config` shows the saved default server).

## Hugging Face token

Gated Hugging Face repos need an access token. Save it once with `zb auth hf set`. The input is hidden. `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. In a script, a bare `--hf-token` reads `$HF_TOKEN`, then the saved 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.

## Next steps

[Quickstart](https://docs.zettabyte.com/docs/zcloud/cli/quickstart): one command to a GPU shell, three to a finished training job.
