# CLI reference

Installed command: `millrace`  
Module entrypoint: `python -m millrace_ai`

## Defaults

- `--workspace` points to the operator workspace root
- runtime config defaults to `<workspace>/millrace-agents/millrace.toml`
- runtime bootstrap and output stay under `<workspace>/millrace-agents/`

## Primary command groups

- `millrace run ...`
- `millrace status ...`
- `millrace runs ...`
- `millrace queue ...`
- `millrace planning ...`
- `millrace config ...`
- `millrace control ...`
- `millrace compile ...`
- `millrace modes ...`
- `millrace doctor`

Compatibility aliases remain for top-level operator commands:

- `millrace add-task`, `millrace add-spec`, `millrace add-idea`
- `millrace pause`, `millrace resume`, `millrace stop`
- `millrace retry-active`, `millrace clear-stale-state`, `millrace reload-config`

These aliases use the same flags and behavior as their grouped forms.

## Run commands

### `millrace run once`

Runs one deterministic startup-plus-tick cycle.

Common options:

- `--workspace PATH`
- `--mode MODE_ID`
- `--config PATH`

### `millrace run daemon`

Runs repeated ticks until stop, interrupt, or `--max-ticks` is reached.

Common options:

- `--workspace PATH`
- `--mode MODE_ID`
- `--config PATH`
- `--max-ticks N`

## Status commands

Canonical operator form: `millrace status`  
Explicit subcommand alias: `millrace status show`

### `millrace status`

Prints runtime snapshot and queue depth for one workspace. When a failure class is active, status also shows the current failure class and non-zero retry counters.

The `execution_status_marker` and `planning_status_marker` fields show the currently running stage marker while a stage is executing. When no stage is active, they fall back to the latest terminal marker or `### IDLE`.

### `millrace status watch`

Polls runtime status repeatedly.

Common options:

- `--workspace PATH` (repeatable)
- `--max-updates N`
- `--interval-seconds FLOAT`

`status watch` is monitor-only and does not acquire runtime ownership locks.

## Run inspection commands

### `millrace runs ls`

Lists persisted run summaries from `millrace-agents/runs/`.

### `millrace runs show <RUN_ID>`

Prints one run summary, including work-item identity, failure class, elapsed time, aggregated token usage, per-stage elapsed time, stdout/stderr paths, and troubleshoot report path when present.

### `millrace runs tail <RUN_ID>`

Prints the primary tailable artifact for one run. Millrace prefers the troubleshoot report first, then stdout/stderr artifacts.

## Queue commands

### `millrace queue ls`

Prints queue and active counts for execution and planning surfaces.

### `millrace queue show <WORK_ITEM_ID>`

Finds and prints one task, spec, or incident document summary by id.

### `millrace queue add-task <task.md|task.json>`

Imports a `TaskDocument`. Canonical queue artifacts are markdown; JSON is import-only.

### `millrace queue add-spec <spec.md|spec.json>`

Imports a `SpecDocument`. Canonical queue artifacts are markdown; JSON is import-only.

### `millrace queue add-idea <idea.md>`

Drops idea markdown into planning intake.

Top-level convenience alias:

- `millrace add-idea <idea.md>`

## Control commands

- `millrace control pause`
- `millrace control resume`
- `millrace control stop`
- `millrace control retry-active --reason "..."`
- `millrace control clear-stale-state --reason "..."`
- `millrace control reload-config`

Control routing behavior:

- if a daemon owns the workspace, the command is mailbox-routed
- if no daemon owns the workspace, the command applies directly

## Planning command

### `millrace planning retry-active --reason "..."`

Requests a retry only when the active work is on the planning plane. If execution work is active instead, the runtime records a skipped retry action rather than mutating the wrong plane.

## Config commands

### `millrace config show`

Prints effective runtime defaults plus the snapshot-exposed config version and last reload outcome or error state.

### `millrace config validate [--mode MODE_ID]`

Loads the effective config, compiles the selected mode, and prints compile diagnostics. This is the preferred operator-facing config validation command.

### `millrace config reload`

Requests a daemon-safe config reload. If recompile fails, the runtime keeps the last known good compiled plan active and records the failure in snapshot state and runtime events.

## Compile and modes

### `millrace compile validate [--mode MODE_ID]`

Compiles the active mode and emits diagnostics such as `ok`, warnings, errors, and fallback usage.

### `millrace compile show [--mode MODE_ID]`

Compiles and prints the operator inspection surface, including:

- graph authority flags and graph entry surfaces
- node request-binding surfaces
- `compiled_plan_id`
- execution and planning loop ids
- frozen `completion_behavior.*` fields when present
- stage ordering
- entrypoint path per stage
- `required_skills` and `attached_skills`

### `millrace modes list`

Lists built-in modes and loop references.

### `millrace modes show MODE_ID`

Prints one mode definition summary.

## Doctor

### `millrace doctor`

Runs workspace integrity diagnostics, including stale lock and ownership checks.

See also:

- `/ai/install.md`
- `/ai/modes-and-loops.md`
- `/ai/architecture.md`