> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veri.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Global flags, environment variables, exit codes, gpu / cost / billing one-liners, and troubleshooting.

Reference material for the `veri` CLI: every global flag, every environment variable, the exit-code contract, the small `gpu` / `cost` / `billing` groups, and `veri doctor` for diagnostics.

## Global flags

Every command accepts these:

| Flag                    | Effect                                                                      |
| ----------------------- | --------------------------------------------------------------------------- |
| `--format <fmt>` / `-o` | Output format: `table`, `json`, `jsonl`, `csv`. Default `table`.            |
| `--json`                | Documented alias for `--format json`.                                       |
| `--quiet` / `-q`        | Suppress banners and progress text. List/create commands print just the ID. |
| `-h` / `--help`         | Show command help.                                                          |
| `--install-completion`  | Install shell completion (bash / zsh / fish).                               |
| `--show-completion`     | Print the completion script to stdout.                                      |

`--format` and `--quiet` work on the root, on groups, and on every leaf command — they are spliced into every command's parameter list by the `VeriTyper` base class.

## Override syntax (`--set`)

Available on every command that loads a TOML config (`jobs create`, `deployments create`, `evals create`, `run`, `jobs estimate`, `config set`).

```bash theme={null}
--set <dotted.key>=<value>           # canonical
--set-string <dotted.key>=<value>    # force string parsing
```

Type coercion uses TOML scalars; repeated flags build lists; scalar-vs-table conflicts error. See [the run-verb reference](/cli/run#override-toml-fields-from-the-cli) for the full rules.

## Help-on-missing-args

`veri` and every group (`veri jobs`, `veri datasets`, etc.) print help when invoked without a subcommand. Commands with required arguments print usage when those arguments are missing. Commands with no required arguments (`veri whoami`, `veri doctor`, `veri logout`, `veri billing balance`) just run.

```bash theme={null}
veri                       # help
veri jobs                  # group help
veri jobs get              # usage: missing ID
veri whoami                # runs
```

## Exit codes

Deterministic across every command. Designed for shell scripting.

| Code  | Meaning                                                   |
| ----- | --------------------------------------------------------- |
| `0`   | Success.                                                  |
| `1`   | User error (validation failed, missing flag, bad config). |
| `2`   | API error (server returned 4xx or 5xx that isn't auth).   |
| `3`   | Network error (timeout, DNS, connection refused).         |
| `4`   | Auth error (401 / 403, missing credentials).              |
| `130` | SIGINT (Ctrl-C).                                          |

```bash theme={null}
veri jobs get job_doesnt_exist
echo $?                    # 2
```

## Environment variables

Highest priority overrides the config file.

| Variable           | Effect                                                                      |
| ------------------ | --------------------------------------------------------------------------- |
| `VERI_API_KEY`     | API key. Overrides the file.                                                |
| `VERI_API_URL`     | API base URL. Overrides the file.                                           |
| `VERI_CONFIG_PATH` | Path to the user config file. Overrides XDG.                                |
| `XDG_CONFIG_HOME`  | Standard XDG override. Config moves to `$XDG_CONFIG_HOME/veri/config.toml`. |
| `VERI_PROFILE`     | Reserved for Phase-2 multi-profile. Ignored today.                          |

```bash theme={null}
# Override the active API key for one command (CI / scripts):
VERI_API_KEY=vk_other_key veri jobs list

# Use a non-default config (e.g., in CI):
VERI_CONFIG_PATH=/tmp/ci-veri.toml veri login --token vk_ci_key
```

## Config file location

Default: `~/.config/veri/config.toml` (XDG-correct on Linux/macOS; `%APPDATA%/veri/` on Windows via `platformdirs`).

The CLI auto-migrates the legacy `~/.veri/credentials.json` on first run **only** when no `VERI_CONFIG_PATH` / `XDG_CONFIG_HOME` is set. The legacy file is renamed to `.json.bak`, not deleted.

```toml theme={null}
# ~/.config/veri/config.toml
active_profile = "default"

[profiles.default]
api_key = "vk_..."
api_url = "https://api.veri.studio"
```

Edit programmatically with the `--set`-style syntax:

```bash theme={null}
veri config show
veri config show --format json
veri config set profiles.default.api_key=vk_new_key
```

## `veri doctor` — diagnostics

```bash theme={null}
veri doctor
```

Runs five checks and reports `pass` / `warn` / `fail` per row:

| Check         | What it verifies                                     |
| ------------- | ---------------------------------------------------- |
| `python`      | Python interpreter version ≥ 3.10.                   |
| `sdk`         | `veri-sdk` is installed and importable.              |
| `config`      | Config file exists and parses.                       |
| `credentials` | An API key is set (file or env var).                 |
| `network`     | The API URL responds to `/health` with HTTP `< 500`. |

`doctor` always exits `0` — it reports, doesn't gate. Read the table, act on warnings. Use `--format json` to consume from CI:

```bash theme={null}
veri doctor --format json | jq -e '.[] | select(.status == "fail")' && exit 1
```

<h2 id="gpu">
  `veri gpu`
</h2>

| Command          | Purpose                                                               |
| ---------------- | --------------------------------------------------------------------- |
| `list`           | Available GPU node SKUs, with per-GPU and whole-node \$/hr.           |
| `describe <sku>` | Hardware specs (VRAM, vCPU, host RAM, node size) + \$/hr for one SKU. |
| `compare`        | Compare cost across providers for a given GPU config.                 |

```bash theme={null}
veri gpu list
veri gpu describe A100-80GB
veri gpu compare --gpu-type A100-80GB --gpu-count 1
```

<h2 id="regions">
  `veri regions`
</h2>

| Command | Purpose                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------- |
| `list`  | Launch regions for training jobs. Marks the default region and whether each region is available or coming soon. |

```bash theme={null}
veri regions list
```

Pass a region to a training job with `veri train --region <name>`, `veri jobs create --region <name>` (or `region` under `[resources]` in the config), or the `region` argument of the `@veri.train` decorator. Omit it to use the default region.

<h2 id="billing">
  `veri billing`
</h2>

| Command                    | Purpose                 |
| -------------------------- | ----------------------- |
| `balance`                  | Current credit balance. |
| `transactions [--limit N]` | Recent billing entries. |

```bash theme={null}
veri billing balance
veri billing transactions --limit 50 --format jsonl
```

<h2 id="wandb">
  `veri wandb`
</h2>

Account-level [Weights & Biases integration](/training/wandb): store your key once and every training job logs to your W\&B account.

| Command                           | Purpose                                                                    |
| --------------------------------- | -------------------------------------------------------------------------- |
| `set [--api-key K] [--project P]` | Store your W\&B API key (prompted with hidden input if omitted).           |
| `status`                          | Whether a key is configured + the default project. The key is never shown. |
| `remove`                          | Disconnect; future jobs stop logging to W\&B.                              |

```bash theme={null}
veri wandb set --project my-experiments
veri wandb status
```

## Shell completion

Typer ships completion for free:

```bash theme={null}
# Install for your current shell (writes to your rc file):
veri --install-completion

# Print the script without installing:
veri --show-completion
```

Supported shells: `bash`, `zsh`, `fish`, `powershell`.

## Versioning

```bash theme={null}
veri version
veri version --format json
```

Prints SDK version, Python version, and platform string. The `--version` and `-v` root flags are aliases — they emit the same output and exit. From CI:

```bash theme={null}
test "$(veri version --format json | jq -r .sdk_version)" = "0.2.0" || exit 1
```

## Phase-2 deferrals

These are not in Phase-1 and will error or print a clear "deferred" note if attempted:

| Feature                                                     | Gated on                                    |
| ----------------------------------------------------------- | ------------------------------------------- |
| `veri jobs logs --follow`                                   | SDK log-streaming method.                   |
| `veri jobs resume`                                          | Resumable training-runner checkpoints.      |
| `veri jobs ssh`                                             | SSH ingress into training containers.       |
| `veri jobs metrics --export wandb`                          | SDK metrics method.                         |
| `veri deployments start` / `scale` / `rollback` / `history` | Server-side versioned deploy history.       |
| `veri deployments load-lora` / `unload-lora`                | Multi-LoRA inference backend.               |
| `veri evals tui`                                            | Textual TUI app.                            |
| `veri evals compare`                                        | Diff logic over two run results.            |
| `veri rewards test --dataset`                               | SDK dataset row iteration.                  |
| Multi-profile (`veri profile use/new`)                      | Forward-compatible schema already in place. |
| `veri secrets`                                              | API secrets surface.                        |

## What's next

<CardGroup cols={3}>
  <Card title="Overview" icon="terminal" href="/cli">
    Install + login + first call.
  </Card>

  <Card title="The run verb" icon="play" href="/cli/run">
    Hero verb + override syntax.
  </Card>

  <Card title="Datasets" icon="database" href="/cli/datasets">
    Upload and connect.
  </Card>
</CardGroup>