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

# Command reference

> Every Cadenza CLI command, subcommand, flag, and argument in one place.

This is the complete catalogue of the Cadenza CLI surface — every top-level
command and every `env` subcommand, with all of their flags.

Prefix each command with `cadenza` (or `cadenza-cli` from a source install).
Inside the [interactive shell](/cli-setup/introduction) you omit the prefix and
type the command directly.

<Info>
  **Which commands need an extra?** The core CLI (scaffold, show, stats, cache,
  finetune-export, account) runs with no extra dependencies. Simulation needs
  `gym`, LoRA needs `lora`, residual RL + distillation need `rl`, and real VLA
  loading needs `vla`. See [Configuration](/cli-setup/configuration#optional-extras).
  Commands that produce a **governed verdict** (`lora eval`, `lora finetune --gate`,
  `residual train/eval/bench`, `distill eval`, `vla grd/eval`) talk to the
  [Cadenza API](/cli-setup/configuration#the-cadenza-api) and require
  [sign-in](/cli-setup/authentication).
</Info>

## Projects

| Command           | Description                                                                    |
| ----------------- | ------------------------------------------------------------------------------ |
| `mkdir <name>`    | Full project scaffold: `env.json` + `main.py` + `requirements.txt` + `README`. |
| `env init <name>` | Light scaffold: `env.json` only.                                               |
| `env show <name>` | Render the mission's zones, objects, and ordered phases.                       |

## Run & analyze

| Command            | Flags                                                                                                         | Description                                                                                                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `env run <name>`   | `--headless`, `--policy scripted\|lora`, `--episodes <n>`, `--max-ticks <n>`, `--no-finetune`, `--xml <path>` | Execute the mission, log every tick, and auto-run the LLM judge at the end. `--policy lora` drives with the fine-tuned LoRA head. Needs the `gym` extra (and `lora` for the LoRA policy). |
| `env stats <name>` | None                                                                                                          | Motion + reward analytics across all cached runs.                                                                                                                                         |
| `env cache <name>` | `--keep-last <n>`, `--older-than <dur>`, `--clear`                                                            | Show or prune the project's `.cadenza-env/` run directory.                                                                                                                                |

<Note>
  On macOS the windowed viewer needs `mjpython`. Pass `--headless`, or relaunch
  with `mjpython -m cadenzalabs`. See [Running missions](/cli/running-missions).
</Note>

## Actions (require sign-in)

| Command                              | Flags                                                                                | Description                                                                                                                                                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `env action create <project> <name>` | `--group`, `--custom`, `--steps '<a,b,c>'`, `--frames-file <file>`, `--robot <name>` | Build an action — a `--group` macro of library steps, or a `--custom` keyframe pose set (interactive editor, or `--frames-file` for scripts). Saved locally **and** synced to your account. |
| `env action list`                    | None                                                                                 | List your account's actions (only your own).                                                                                                                                                |
| `env action show <project> <name>`   | None                                                                                 | Inspect a local project action.                                                                                                                                                             |
| `env action remove <project> <name>` | None                                                                                 | Delete a local project action.                                                                                                                                                              |

## Fine-tuning data & prompts

| Command                        | Flags       | Description                                                                                               |
| ------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------- |
| `env finetune <project> <log>` | `-o <file>` | Emit `(prompt, action, reward)` records from a run log for VLA SFT.                                       |
| `env train <project>`          | None        | Groq **LLM-as-Judge** analyzes the runs and rewrites the project's `SYSTEM_PROMPT`. Needs `GROQ_API_KEY`. |

## LoRA action head (`lora` extra)

Fine-tunes and governs the `cadenza-lab` LoRA action head for a project (on the
project's own base/VLA if it ships a `lora_encoder.py`). See
[Training & fine-tuning](/cli/training-and-lora).

| Command                              | Flags                                                                               | Description                                                                                                                                           |
| ------------------------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `env lora add <project> "<goal>"`    | `--steps '<...>'`, `--image <path>`                                                 | Add a goal→action training example (optionally with visual context).                                                                                  |
| `env lora data <project>`            | `--finetune <path>`                                                                 | Show the current training dataset.                                                                                                                    |
| `env lora finetune <project>`        | `--epochs <n>`, `--lr <x>`, `--rank <r>`, `--finetune <path>`, `--no-env`, `--gate` | Generate goal→action data and fine-tune the adapter. `--gate` runs the [governance scorecard](/cli/governance) and promotes/rolls back automatically. |
| `env lora eval <project>`            | `--promote`                                                                         | Run the governance scorecard on the trained adapter; `--promote` deploys it if it passes.                                                             |
| `env lora decode <project> "<goal>"` | None                                                                                | Decode a goal into actions using the trained adapter.                                                                                                 |

## Residual RL (`rl` extra)

Closed-loop residual RL on the **frozen** base: `a = clamp(a_base + α·gate·Δa)`.
Runs on a deterministic proxy task without `cadenza-lab`; `--real` targets the
gated sim seam. See [Residual RL & distillation](/cli/residual-and-distill).

| Command                        | Flags                                                                                                          | Description                                                                                                                                              |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `env residual init <project>`  | `--hidden-dim <h>`, `--alpha <a>`, `--obs-dim <n>`, `--rate-limit <r>`, `--no-gate`, `--device cuda\|mps\|cpu` | Scaffold `residual/residual.json` and dry-run profile the head (params / per-step ms / peak memory) before any training.                                 |
| `env residual show <project>`  | None                                                                                                           | Show the residual config + artifact status (config / trained policy / rollback snapshot).                                                                |
| `env residual train <project>` | `--device cuda\|mps\|cpu`                                                                                      | API-governed PPO training of the residual head on the frozen base. Saves `residual/residual_policy.pt`. Requires sign-in.                                |
| `env residual eval <project>`  | `--promote`                                                                                                    | Governance scorecard (success / collision / residual-sanity / regression) → `DEPLOY \| BLOCK \| NEEDS_DATA`, with rollback on `BLOCK`. Requires sign-in. |
| `env residual bench <project>` | `--steps <n>`, `--cost-per-gpu-hour <x>`, `--device <d>`, `--real`                                             | Head-to-head: current full-RL stack vs cadenza-cli residual RL — compute / cost / accuracy + a verdict. Requires sign-in.                                |

## Distillation (`rl` extra)

Distill the residual teacher into a compact, base-free student that runs on
CPU/MPS (optional int8). See [Residual RL & distillation](/cli/residual-and-distill).

| Command                      | Flags                                        | Description                                                                                                                                                  |
| ---------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `env distill <project>`      | `--epochs <n>`, `--quantize`, `--device <d>` | Train the student from the residual teacher; report the teacher↔student gap, param count, and onboard latency vs the 50 Hz control budget. Saves `student/`. |
| `env distill eval <project>` | `--promote`                                  | Governance scorecard on the student (gap / success / regression) → `DEPLOY \| BLOCK \| NEEDS_DATA`, with rollback on `BLOCK`. Requires sign-in.              |

## VLA-only mode + GRD (`lora` extra; `vla` for real models)

A VLA-only project is a model + an action library in `vla.json` — no `env.json`,
no prompts. The **GRD** loop adapts only the model's LoRA adapter in one governed
fine-tune + RL pass. See [VLA mode & GRD](/cli/vla-mode).

| Command                            | Flags                                                                                         | Description                                                                 |
| ---------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `env vla init <name>`              | `--robot <name>`, `--model default\|smolvla\|hf\|local`, `--model-id <repo\|path>`, `--force` | Scaffold `vla.json` (model + action library).                               |
| `env vla show <name>`              | None                                                                                          | Show the config + action library.                                           |
| `env vla data <name> add "<goal>"` | `--steps '<...>'`                                                                             | Author a goal→action pair. Bare `env vla data <name>` lists the dataset.    |
| `env vla grd <name>`               | `--lambda <l>`, `--rl-budget <n>`, `--change-cap <c>`, `--rounds <r>`, `--device <d>`         | Run the API-governed GRD loop on the model's adapter. Requires sign-in.     |
| `env vla eval <name>`              | `--promote`                                                                                   | One-shot GRD governance scorecard on the current adapter. Requires sign-in. |

## Megan (require sign-in)

Use Cadenza as an API from your own project — your token is the API key. The
Megan SDK (`from cadenzalabs import MeganTK`) is standard-library only; these
two CLI commands support it. See the [Megan guide](/megantk/introduction).

| Command  | Flags        | Description                                                                                   |
| -------- | ------------ | --------------------------------------------------------------------------------------------- |
| `apikey` | `--reveal`   | Show your token as a megan-tk API key + a paste-ready SDK snippet (masked unless `--reveal`). |
| `usage`  | `--days <n>` | Per-route call counts + a session/anticipator rollup over the last `<n>` days (default 30).   |

## Account & shell

| Command                          | Description                                                                                                                                                                   |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `login <name> <token>`           | Sign in and save a session to `~/.cadenza/config.json`. The token comes from an admin via the `cadenza-admin` CLI.                                                            |
| `logout`                         | Forget the saved session.                                                                                                                                                     |
| `whoami`                         | Show the signed-in account.                                                                                                                                                   |
| `apikey [--reveal]`              | Show your token as a **Megan API key** with a paste-ready SDK snippet (masked unless `--reveal`). Requires sign-in. See [Megan](/megantk/introduction).                       |
| `usage [--days <n>]`             | Show your megan-tk API usage: per-route calls + a session/anticipator rollup over the last `<n>` days (default 30). Requires sign-in. See [Usage & metering](/megantk/usage). |
| `help` (or `?`)                  | Show the in-shell command table.                                                                                                                                              |
| `clear`                          | Clear the screen and re-render the banner (also `Ctrl+L`).                                                                                                                    |
| `--version` (or `-v`, `version`) | Print the version and check for a newer release.                                                                                                                              |

<Tip>
  The interactive shell tab-completes top-level commands and `env` subcommands with
  inline descriptions. `↑`/`↓` walk history, `Ctrl+L` clears, `Ctrl+C` exits.
</Tip>