# CLI

The `gpu-engine` executable is defined in `package.json` (`bin`). The package is marked `private: true` and is not published on npm yet; build and install a local tarball as shown in [Quick start](https://gpu-engine.dev/docs/start/quick-start). All six commands work today.

## Command overview

| Command | Purpose | Reads test set |
| --- | --- | --- |
| `gpu-engine new` | Scaffold a model package: model and eval files, `src/`, build script, `AGENTS.md`, `SPEC.md`, skill and CI (writes no data files) | No |
| `gpu-engine loop` | Data, checks, train, dev table with baselines and oracle, gate; appends a try | No (digest only) |
| `gpu-engine promote` | The only command that reads the test set: scores, gates and writes the promoted model (`--verify` for CI, `--seal` for level 3) | Yes (`--verify` and `--seal`: digest only) |
| `gpu-engine parity` | Trainer = CPU = WGSL on dev and edge fixtures; writes `parity.json` | No |
| `gpu-engine inspect` | Tokens, feature rows, raw output, decoded result, backend and reason | No |
| `gpu-engine doctor` | Every static check, each finding with its code, why and fix | No (digest only) |

## Help, `--dir` and error format

- `gpu-engine --help` (or `-h`) prints the command list and exits 0. Running `gpu-engine` with no arguments prints help to stderr and exits 1.
- `gpu-engine <command> --help` prints usage and flags for that command and exits 0.
- Flags that take a value accept either `--flag value` or `--flag=value`.
- Every command accepts `--dir <path>` to target a package folder (or destination parent folder for `new`; defaults to the current working directory).
- Unknown commands fail with `CLI_COMMAND_UNKNOWN`; unknown flags, missing flag values, invalid enum values or wrong positional counts fail with `CLI_FLAG_INVALID`. Both exit 1:

```txt
CLI_FLAG_INVALID: `loop` has no flag --bogus
  why: A flag is unknown for this command, is missing its value, or a required argument is missing.
  fix: Run `gpu-engine <command> --help` to see its arguments and flags.
```

See [Diagnostics](https://gpu-engine.dev/docs/reference/diagnostics) for every CLI and harness code.

## `gpu-engine new`

Scaffolds a model package into `<dir>/<name>` from `templates/`: `<name>.model.ts`, `<name>.eval.ts`, `src/decode.ts`, `src/index.ts`, `src/weights.ts`, `scripts/build.ts`, `AGENTS.md`, `SPEC.md`, `skills/gpu-engine/SKILL.md`, `.github/workflows/ci.yml`, `package.json`, `tsconfig.json` and `.gitignore` (plus `data/table.jsonl` and `src/table.ts` for `--head retrieve`). Writes no data files; the starter's generators run on the first `loop`.

```txt
gpu-engine new <name> --head tag|pooled|retrieve [--dir <path>]
```

| Argument / flag | Meaning |
| --- | --- |
| `<name>` | Required package and model name; must match `^[a-z][a-z0-9-]{0,63}$` (`NEW_NAME_INVALID`). Never overwrites a folder holding any file (`NEW_TARGET_EXISTS`). |
| `--head <kind>` | Required: `tag`, `pooled` or `retrieve` (`head kind of the model`). |
| `--dir <path>` | Folder to create the package in (default: the working directory). |

## `gpu-engine loop`

Runs the level 1 scan and data step, trains all seeds, scores `data/dev/` alongside baselines and the oracle, evaluates dev gate lines, writes `.gpu-engine/candidate.bin` and checkpoints, and appends one row to `tries.jsonl`. Exits 0 if all gate lines pass, 1 otherwise. Never reads `data/test/`.

```txt
gpu-engine loop [--log "<idea>"] [--status kept|dropped] [--fail [--set <name>]] [--mark kept|dropped] [--dir <path>]
```

| Flag | Meaning |
| --- | --- |
| `--log <idea>` | What this try changes, written to `tries.jsonl`. |
| `--status <status>` | Mark the try as `kept` or `dropped` (`null` when omitted). |
| `--fail` | List dev misses only; trains nothing and appends no try. |
| `--set <name>` | With `--fail`, one dev set. |
| `--mark <status>` | Train nothing; mark the last try `kept` or `dropped` once (sets a `null` status on the last row of `tries.jsonl`). Takes no other `loop` flag besides `--dir`; exits 1 with `CLI_FLAG_INVALID` if no try exists or the last try already has a status. |
| `--dir <path>` | Model package folder (default: the working directory). |

## `gpu-engine promote`

Promotes the candidate, verifies a committed promotion in CI, or encrypts the test set for level 3 sealing.

```txt
gpu-engine promote [--verify] [--seal [--key-out <path>]] [--dir <path>]
```

| Flag | Meaning |
| --- | --- |
| *(none)* | The only command that reads `data/test/`. At level 3 requires `CI=true` (`PROMOTE_OUTSIDE_CI`) and 64-hex `GPU_ENGINE_TEST_KEY` (`SEAL_KEY_MISSING`, `SEAL_KEY_INVALID`). Validates candidate freshness, counts the test read in `reads.jsonl`, scores dev and test (muting `console`, stdout and stderr during test scoring), checks all gate lines, screens outgoing text for test inputs, and writes `weights/<name>.bin`, `src/weights.ts`, `gate.json`, `report.json`, `MODEL_CARD.md` and `RESULTS.md`. |
| `--verify` | Check the committed promotion without reading test data (the CI gate). Needs no level 3 key. Checks level 1 scan, `report.json`, locked hashes (or sealed `plaintext` hashes for pre-seal reports), weights, fresh dev scores, `gate.json`, budgets, dev floors, `reads.jsonl` read count and byte-identical regeneration of generated files. |
| `--seal` | Encrypt the test set so only CI can read it (level 3). Runs once per package: runs the data step, writes a 256-bit hex key outside the working tree (mode `0600`, never printed), encrypts each test file with AES-256-GCM to `.enc`, updates `data.lock.json` and `gate.json`, writes `.github/workflows/promote.yml` and deletes plaintext test files. |
| `--key-out <path>` | With `--seal`, where to write the key, resolved against the package folder (default: `~/.gpu-engine/keys/<model name>.key`, outside the working tree). |
| `--dir <path>` | Model package folder (default: the working directory). |

## `gpu-engine parity`

Compares the promoted weights (`weights/<name>.bin`, verified against `report.json`) across the trainer's forward pass, the CPU runtime and the WGSL runtime on every dev input plus four edge inputs (empty text, one token, `input.max` tokens and `input.max + 3` tokens). For `retrieve` models, compares scores against `eval.table`. Never reads `data/test/`.

Needs the `webgpu` package installed in the model package (`npm install --save-dev webgpu@^0.6.2`) and a Vulkan driver (`PARITY_ADAPTER_MISSING` otherwise). On a pass, writes `parity.json` (keeping existing bytes if only `date` would change) and regenerates `MODEL_CARD.md`. Exits 1 on `PARITY_DECODE_DIFFERS`, `PARITY_TOLERANCE_EXCEEDED` or `PARITY_ADAPTER_MISSING`.

```txt
gpu-engine parity [--dir <path>]
```

| Flag | Meaning |
| --- | --- |
| `--dir <path>` | Model package folder (default: the working directory). |

## `gpu-engine inspect`

Runs one input string (with all flags off) through the model and prints each section in order:

1. `input`: the quoted input string with a note that every flag is off.
2. `tokens`: token list with UTF-16 offsets and count of tokens cut after `input.max`.
3. `feature rows`: feature rows per kept token in definition order (`-` for empty slots).
4. `weights`: loaded weights path and byte size (`weights: <path> (promoted, N bytes)`, or the candidate path followed by a note when nothing is promoted).
5. `raw output`: raw logits returned by the forward pass (or scores per table row for `retrieve`).
6. `head output`: raw head output JSON.
7. `decoded result`: output of `eval.decode(output, text)` (or the head output with a note when the eval defines no `decode`).
8. `backend`: the backend that ran.
9. `reason`: the reason that selected that backend.

```txt
gpu-engine inspect "<text>" [--dir <path>]
```

| Argument / flag | Meaning |
| --- | --- |
| `<text>` | Required input string to inspect. |
| `--dir <path>` | Model package folder (default: the working directory). |

`inspect` loads `weights/<name>.bin` if promoted; otherwise it loads `.gpu-engine/candidate.bin` and prints a note that nothing is promoted. If neither file exists, it prints tokens and feature rows, then exits 1 with `PROMOTE_CANDIDATE_MISSING`. It loads with `backend: 'auto'` and `definition` (catching `WEIGHTS_DEFINITION_MISMATCH` if the model file changed), opens no data file except `eval.table` for a `retrieve` model, takes no digest and writes nothing to `reads.jsonl`.

## `gpu-engine doctor`

Runs every static check that requires no training and no test read:

- Loads `*.model.ts` and `*.eval.ts` and runs define-time checks (`PROJECT_*`, `DEFINE_*`).
- Runs the level 1 scan (`DATA_TEST_READ`).
- Runs section 7 data checks with a test-set digest (`DATA_*`). Empty folders with declared generators and missing `data.lock.json` entries print notes instead of failing.
- Parses `gate.json` if present (`GATE_FILE_INVALID`).
- Checks `weights/<name>.bin` against `budgets.brotliBytes` if present (`BUDGET_BYTES_EXCEEDED`).
- Verifies `report.json` agreement with the model hash, weights file, `data.lock.json`, `gate.json`, `reads.jsonl` and generated files (`VERIFY_*`, `WEIGHTS_DEFINITION_MISMATCH`, `DATA_HASH_CHANGED`) when `report.json` exists or `gate.json` records a promotion.
- Runs ship checks (`SHIP_*`) when `dist/` exists (prints a note if `dist/` is absent or if `eval.ship` is omitted).
- Runs level 3 checks (`SEAL_PLAINTEXT_FOUND`, `SEAL_LOCK_INVALID`, `SEAL_WORKFLOW_MISSING`) when `gate.json` is at level 3.

`doctor` writes no data files, writes no lock file, runs no generators and invokes no package callback (`metric`, `decode`, `baselines` or `generate`). The only file it appends to is `reads.jsonl` with its `digest` row. It exits 0 when there are no findings and 1 otherwise.

```txt
gpu-engine doctor [--dir <path>]
```

| Flag | Meaning |
| --- | --- |
| `--dir <path>` | Model package folder (default: the working directory). |

Source: SPEC sections 6, 7, 10, 11 and 12, and `src/cli/main.ts`.

<!-- vitehub-docs:section-links -->
## In this section

- [Layer catalog](https://gpu-engine.dev/raw/docs/reference/layers.md)
- [CLI](https://gpu-engine.dev/raw/docs/reference/cli.md) (this page)
- [Diagnostics](https://gpu-engine.dev/raw/docs/reference/diagnostics.md)

Next: [Diagnostics](https://gpu-engine.dev/raw/docs/reference/diagnostics.md)

All pages: [llms.txt](https://gpu-engine.dev/llms.txt)
