> ## Documentation Index
> Fetch the complete documentation index at: https://hud-f5fd7c15-lukass-phys-experimental.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Reference for the hud command-line interface: init, dev, run, eval, models, and other commands that span the HUD environment and agent lifecycle.

Install the CLI with `uv tool install hud-python --python 3.12`. Authenticate once with `hud set HUD_API_KEY=...`.

## Build & iterate

### `hud init`

Scaffold a new environment package in a fresh `<name>` directory. The `blank` template (the default with no preset, and the first option in the interactive picker) writes a minimal local scaffold - `env.py` (environment, templates, capabilities), `tasks.py` (concrete task rows), `Dockerfile.hud`, and `pyproject.toml` - no network, no API key. Every other preset downloads a starter environment from GitHub instead.

```bash theme={null}
hud init                          # pick a template → ./<template>
hud init my-env                   # pick a template (or minimal scaffold) → ./my-env
hud init my-env --preset browser  # download the "browser" starter into ./my-env
hud init --preset cua             # download the "cua" starter into ./cua-template
hud init my-env --dir envs        # create ./envs/my-env
```

| Option           | Description                                                                                                                                                                                                                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--preset`, `-p` | Starter to use: `blank` (minimal local scaffold), `browser`, `cua`, `deepresearch`, `coding`, `ml`, `ml-triage`, `verilog`, `autonomous-businesses`, `gdpval`, `worldsim`, `videogamebench` (all downloaded from GitHub). Omit for the interactive picker (TTY); with a `NAME` in a non-interactive shell, omitting it writes the blank local scaffold. |
| `--dir`, `-d`    | Parent directory (default `.`).                                                                                                                                                                                                                                                                                                                         |
| `--force`, `-f`  | Overwrite existing files.                                                                                                                                                                                                                                                                                                                               |

### `hud serve`

Serve an environment's control channel locally (tcp JSON-RPC). `hud dev` is a
deprecated alias.

```bash theme={null}
hud serve               # auto-detect env.py
hud serve env:env       # explicit module:attribute
hud serve env.py -p 9000
```

| Option            | Default     | Description                                          |
| ----------------- | ----------- | ---------------------------------------------------- |
| `--port`, `-p`    | `8765`      | Port to serve on.                                    |
| `--host`          | `127.0.0.1` | Interface to bind (use `0.0.0.0` inside containers). |
| `--verbose`, `-v` | -           | Detailed logs.                                       |

### `hud deploy`

Build **and** publish to HUD infra in one step. The environment's name comes
from the `Environment(...)` declaration in code; deploying the same name again
rebuilds that environment.

```bash theme={null}
hud deploy
```

| Option        | Description                               |
| ------------- | ----------------------------------------- |
| `--all`, `-a` | Deploy all environments in the directory. |
| `--env`, `-e` | Env var `KEY=VALUE` (repeatable).         |
| `--env-file`  | Path to a `.env` file.                    |

## Evaluate

### `hud eval`

The primary local iteration loop: run an agent over a task source (`.py`, directory, or JSON/JSONL), grade the result, and print the reward. Each rollout gets a **fresh subprocess** for the env - no shared state between tasks.

```bash theme={null}
# Split layout (hud init): templates in env.py, task rows in tasks.py
hud eval tasks.py claude
hud eval tasks.py claude --full --group 3

# Single-file layout: env + tasks list in one file
hud eval env.py claude
hud eval env.py claude --model claude-haiku-4-5   # cheaper model for fast iteration
hud eval env.py claude --max-steps 30
hud eval env.py claude --all                      # every task, not just the first
hud eval env.py claude --full                     # every task, auto-respond, 100 steps
```

<Note>
  `hud eval` loads tasks from the path you pass. In a split project, point it at `tasks.py` (or `.` to scan the directory). It spawns `env.py` for the control channel automatically - you don't pass both files.
</Note>

**What you don't need for a local run:**

* A HUD API key - local evals don't hit the platform
* `hud serve` running - `hud eval` spawns the env subprocess for you
* Docker - unless your env explicitly uses `DockerRuntime`
* An SSH connection - the gateway timeout only applies when `env.workspace()` is declared

For a platform taskset, pass its name or id directly: `hud eval "My Tasks" claude`. The tasks are fetched from the platform and the rollouts run remotely by default, since the env source is not on disk.

**Single-task runs** show step-by-step progress (step number + tool calls). Multi-task batches are silent unless `--verbose` is passed.

| Option                           | Description                                                                                                                                                          |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--full`                         | Run the whole dataset (`--all --auto-respond --max-steps 100`).                                                                                                      |
| `--all`                          | Run every task instead of just the first.                                                                                                                            |
| `--model`, `-m`                  | Model id.                                                                                                                                                            |
| `--gateway`, `-g`                | Force LLM calls through the HUD gateway. Implied when only `HUD_API_KEY` is set (no provider key); pass it to force the gateway when a provider key is also present. |
| `--group` (alias `--group-size`) | Runs per task - a group of repeats whose reward spread you can inspect.                                                                                              |
| `--max-concurrent`               | Cap parallel rollouts.                                                                                                                                               |
| `--max-steps`                    | Cap steps per task (default 10).                                                                                                                                     |
| `--task-ids`                     | Comma-separated slugs or 0-based indices.                                                                                                                            |
| `--config`, `-c`                 | Agent config `key=value` (repeatable).                                                                                                                               |
| `--verbose`, `-v`                | Show agent logs (step progress, tool calls) for batch runs too.                                                                                                      |
| `--very-verbose`, `-vv`          | Debug-level logs.                                                                                                                                                    |
| `--runtime`                      | Placement: `local`, `hud` (HUD runtime tunnel), or `tcp://host:port`. Defaults to `local` for a tasks file; platform tasksets default to remote hosted execution.    |
| `--remote`                       | Run the whole rollout remotely on the HUD platform.                                                                                                                  |
| `--yes`, `-y`                    | Skip confirmation prompt.                                                                                                                                            |

## Run a packaged image

`hud task start` / `hud task grade` attach to an env already serving locally (e.g. inside a built image, or alongside `hud serve`), or load one from source with `--source`. `hud task list` always reads from source (default `.`) - it doesn't attach.

```bash theme={null}
hud task list                          # what tasks are exposed
hud task start fix_bug                 # -> the prompt (stdout)
hud task grade fix_bug --answer "..."  # -> the reward (stdout)
```

| Command                 | Key options                                                         |
| ----------------------- | ------------------------------------------------------------------- |
| `hud task start <task>` | `--source`/`-s`, `--args` (JSON), `--url`/`-u`, `--out`/`-o`        |
| `hud task grade <task>` | `--answer`, `--answer-file`, `--source`, `--args`, `--url`, `--out` |
| `hud task list`         | `--source`/`-s`                                                     |

## Platform

```bash theme={null}
hud sync tasks my-taskset      # publish tasks as a named taskset
hud sync env                   # sync environment metadata
```

External benchmark formats (currently Harbor) load directly into the runtime
as `Taskset`s - no conversion step. See [Harbor interop](/v6/advanced/harbor-convert).

## Inspect

### `hud jobs [<id>]`

Without an id, lists your most recent jobs. With an id, lists every trace in that job.

```bash theme={null}
hud jobs               # recent jobs - id, name, taskset, status, created
hud jobs <job-id>      # traces for one job - trace id, status, reward, error
hud jobs --json        # raw JSON
hud jobs -n 50         # show up to 50 rows (default 20)
```

### `hud trace <trace_id>`

Inspect a single rollout. Reads from the local telemetry JSONL file first
(`HUD_TELEMETRY_LOCAL_DIR/<trace_id>.jsonl`) and falls back to the platform API.

```bash theme={null}
hud trace <trace-id>          # rendered view: agent turns, tool calls, tool results
hud trace <trace-id> --json   # raw event list
```

Set `HUD_TELEMETRY_LOCAL_DIR` in your environment to write spans to disk during a
rollout so `hud trace` can read them offline without an API call.

## Other commands

| Command                                           | Description                                                    |
| ------------------------------------------------- | -------------------------------------------------------------- |
| `hud set KEY=VALUE`                               | Persist credentials/vars to `~/.hud/.env`.                     |
| `hud login`                                       | Authenticate with HUD.                                         |
| `hud models list`                                 | List gateway models.                                           |
| `hud models fork <model> --name <slug>`           | Fork a trainable model from an existing one.                   |
| `hud models checkpoints <model>`                  | List a model's checkpoint tree.                                |
| `hud models head <model> [--set <checkpoint-id>]` | Show - or set (rollback/select) - a model's active checkpoint. |
| `hud cancel`                                      | Cancel a running job.                                          |
| `hud version`                                     | Show the CLI version.                                          |

## See also

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/v6/start/quickstart" />

  <Card title="Run & deploy" icon="rocket" href="/v6/reference/runtime" />
</CardGroup>