Command line
Every verb the binary answers to and every flag it parses, with the builds that have them.
The verbs
CLI verbs — 23 rows
of 35 exported from src/engine/cli_specification.rs
| command | arguments | what it does |
|---|---|---|
|
gantry list
also gantry ls |
— | active runs by name, state, and progress (alias: ls; -v/--verbose adds finished) |
|
gantry ps
also gantry processes |
— | unfinished runs: the owning engine, and a row per process group each run still holds (state, group id, work, elapsed, CPU, memory) |
| gantry ps | <name> | one run's whole process history, reaped and exited groups included, with the launch and reap times the roster recorded |
| gantry ps | [<name>] --watch | re-render either form every 2s until Ctrl-C (read-only, no TUI) |
| gantry enter | [<name>] | open a shell in a run's worktree and write a GANTRY-STATUS.md guide (defaults to the lone active run) |
| gantry status | <name> | show a run's details and its ledger |
|
gantry logs
also gantry log |
<name> [-f] | tail a run's activity journal (-f follows until it is no longer active) |
|
gantry remove
also gantry rm |
<name> [--live] [--process-safety] | tear down a run by name (alias: rm) |
| gantry stop | <name> | stop a live owner or clean up verified dead-owner processes |
| gantry prune | <name>|--all [--dry-run] [--yes] [--older-than <days>] | rewrite detailed transcripts while keeping the readable run account |
| gantry purge | <name>|--all [--dry-run] [--yes] [--older-than <days>] | delete detailed transcripts while keeping the run record |
|
gantry worktrees
also gantry worktree |
<name>|--all [--dry-run] [--yes] [--older-than <days>] | remove stale worktrees |
|
gantry build-directories
also gantry build-directory |
<name>|--all [--dry-run] [--yes] [--older-than <days>] | remove rebuildable output |
| gantry resume | [<name>] | resume a run by name; unnamed resumes the lone run or opens a TTY picker (aliases: --resume [<name>], -r [<name>]; newest: --last, --continue, -c) |
| gantry merge | <name> | merge a capable run's committed branch-tip work to its target branch, keep it resumable (--yes) |
| gantry mcp | <name> | start a stdio MCP server scoped to one run (read tools for an assistant) |
| gantry stats | — | print the native fleet statistics dashboard |
| gantry stats | --json [--runs|--sessions] | emit native fleet statistics JSON/JSONL |
| gantry pattern | show <name> --ascii [--detail blocks|steps|full] | render a static pattern diagram |
| gantry pattern | snapshots --ascii [--out <dir>] | write shipped pattern diagram review snapshots |
| gantry config | — | show the global config path and harness default |
| gantry config | harness <id> | set the global harness default (use --unset or "" to clear) |
| gantry config | reset | restore the default prompts, discarding local edits (--yes to skip the prompt) |
| gantry unlock | <code> | redeem a demo purchase code and cache unlimited builds demo edition only |
| gantry triage | <plan> | report which pattern a run would use for a plan, and the whole registry, starting nothing |
| gantry backfill-names | [<repo-dir>] | pin a permanent name for every run that has none (re-runnable) |
| gantry doctor | — | dependency-readiness report; works outside a repo |
|
gantry agent
handled before verb detection |
[--headless] <message>… | diagnostic one-turn driver for the conversational assistant; several quoted messages run as one conversation not in gantry --help |
|
gantry mcp-bridge
handled before verb detection |
<socket> | internal stdio↔socket pump the assistant's MCP registration points at not in gantry --help |
The flags
CLI flags — 55 rows
of 87 exported from src/engine/cli_specification.rs
| flag | applies to | what it does |
|---|---|---|
|
--help
spelt --help, -h |
any invocation | print the usage text and exit not in gantry --help |
|
--version
spelt --version, -V |
any invocation | print `gantry <version> (<short sha>)` and exit not in gantry --help |
|
gantry <plan> [--headless|-p|--print] [--json]
spelt --headless, -p, --print |
gantry <plan>, gantry replay, gantry agent | build a file, directory, or inline plan via milestones (small plans collapse to one pass) |
| -p, --print, --headless | gantry <plan>, gantry replay, gantry agent | print non-interactive plain lines instead of opening the TUI |
|
--json
spelt --json |
gantry <plan>, gantry stats | with --headless/-p/--print, emit newline-delimited JSON event records with `gantry stats`, emit aggregate JSON; add --runs or --sessions for JSONL rows |
|
gantry <plan> --detach
spelt --detach |
gantry <plan> | launch headless in a new session (setsid), engine records run.pid |
| --detach | gantry <plan> | relaunch under setsid (implies --headless --json), capture output to .gantry/<plan>/detach.log; the child writes run.pid when it owns the run |
|
gantry <plan> --allow-nested-run
spelt --allow-nested-run |
gantry <plan> | bypass Gantry-inside-Gantry start guards only |
| --allow-nested-run | gantry <plan> | explicitly bypass start guards for managed worktree ancestry or Gantry-launched agent environments; does not override live-owner or process-safety removal checks |
|
gantry <plan> --clean
spelt --clean |
gantry <plan> | wipe a botched run (worktree, branch, run dir) then build fresh |
| --clean/--remove | gantry <plan> | dry-run by default (print what they'd delete); add --yes to skip the prompt. |
|
gantry <plan> --remove
spelt --remove |
gantry <plan> | wipe a botched run and exit (abandon the plan) |
|
--live
spelt --live |
gantry remove |
tear the run down even though its owner process is still alive
in gantry --help under
gantry remove
|
|
--process-safety
spelt --process-safety |
gantry remove |
hold the teardown to the process-safety checks rather than forcing it through
in gantry --help under
gantry remove
|
|
--yes
spelt --yes, -y |
gantry <plan>, gantry remove, gantry merge, gantry prune, gantry purge, gantry worktrees, gantry build-directories, gantry config |
skip the confirmation prompt
in gantry --help under
--clean, gantry prune, gantry purge, gantry worktrees, gantry build-directories, gantry merge, gantry config
|
|
--verbose
spelt --verbose, -v |
gantry list |
list finished runs as well as active ones
in gantry --help under
gantry list
|
|
--all
spelt --all, -a |
gantry list, gantry prune, gantry purge, gantry worktrees, gantry build-directories |
act on every eligible run instead of one named one
in gantry --help under
gantry prune, gantry purge, gantry worktrees, gantry build-directories
|
|
--follow
spelt --follow, -f |
gantry logs |
follow the journal until the run is no longer active
in gantry --help under
gantry logs
|
|
--watch
spelt --watch |
gantry ps |
re-render the process view every 2s until Ctrl-C
in gantry --help under
gantry ps
|
|
--dry-run
spelt --dry-run |
gantry prune, gantry purge, gantry worktrees, gantry build-directories, gantry repair, gantry repairs |
report what would change without changing anything
in gantry --help under
gantry prune, gantry purge, gantry worktrees, gantry build-directories, gantry repair, gantry repairs
|
|
--older-than <days>
spelt --older-than value required |
gantry prune, gantry purge, gantry worktrees, gantry build-directories |
restrict the sweep to runs older than <days> days
in gantry --help under
gantry prune, gantry purge, gantry worktrees, gantry build-directories
|
|
--resume [<name>]
spelt --resume, -r value optional |
gantry resume |
resume a run by name, as an alias for `gantry resume [<name>]`
in gantry --help under
gantry resume
|
|
--last
spelt --last, --continue, -c |
gantry resume |
resume the newest resumable run
in gantry --help under
gantry resume
|
|
--map <spec>
spelt --map value required |
gantry <plan> | run an explicit Map fan-out over a map spec |
|
gantry --pattern <name|file.toml> [inputs…]
spelt --pattern value required |
gantry <plan> | run a discoverable pattern with typed inputs |
| --pattern <name|file.toml> | gantry <plan> | select a pattern by discovery name or TOML file path; inputs bind positionally or as name=value against [[header.parameters]] |
|
gantry --design pages.md
spelt --design value required |
gantry <plan> | alias for `gantry --pattern design pages_source=pages.md` |
| --design <pages.md> | gantry <plan> | start the additive bundled design pattern over a surface index |
|
gantry --redesign pages.md
spelt --redesign value required |
gantry <plan> | alias for `gantry --pattern redesign pages_source=pages.md` |
| --redesign <pages.md> | gantry <plan> | start the clean-slate bundled redesign pattern over a surface index |
|
gantry --loop goal.md
spelt --loop value required |
gantry <plan> | loop whole-plan builds until the frozen goal check passes |
| --loop <goal.md> | gantry <plan> | start a Goal run: freeze goal:, prove it starts amber, then build cycles |
|
gantry --goal goal.md
spelt --goal value required |
gantry <plan> | alias for `gantry --loop goal.md` |
| --goal <goal.md> | gantry <plan> | permanent alias for --loop |
|
gantry --ralph prompt.md
spelt --ralph value required |
gantry <plan> | run guarded Ralph Loop iterations over one standing prompt |
| --ralph <prompt.md> | gantry <plan> | start a Ralph Loop run: freeze optional goal:, prove baseline, then iterate |
|
--max-cycles <N>
spelt --max-cycles value required |
gantry <plan> | Optional Goal cycle ceiling (default: unlimited); overrides front matter |
|
--max-iters <N>
spelt --max-iters value required |
gantry <plan> | Ralph Loop iteration ceiling (default 100); overrides prompt front matter |
|
--quiesce-after <N>
spelt --quiesce-after value required |
gantry <plan> | Ralph Loop empty-iteration threshold (default 2); overrides front matter |
|
--jobs <N>
spelt --jobs value required |
gantry <plan> | Map worker-pool width override; defaults to the pattern's pool_width |
|
--
spelt -- |
gantry <plan>, gantry screencast | end Gantry's own option parsing; everything after it is opaque slice pass-through not in gantry --help |
|
--harness <id>
spelt --harness value required |
gantry <plan> | pick the harness for every role (claude | codex | opencode | gemini) |
| gantry <plan> | e.g. gantry --harness opencode plan.md · gantry --harness-build opencode --harness-review codex plan.md A per-role flag overrides the run-wide one; both override any run-local harness.toml pin and the startup/global default fallback. --harness-assistant also overrides the run-wide flag and the assistant key in the relevant harness.toml. A run remembers whichever harnesses it was first built with, so `gantry resume` keeps them without re-passing any flag; an explicit --harness* on the resume overrides (and warns). | |
|
--harness-<role> <id>
spelt --harness-plan value required |
gantry <plan> | pick a harness per role: --harness-plan / -build / -review / -util |
|
--harness-build <id>
spelt --harness-build value required |
gantry <plan> |
pick the harness that runs the build role
in gantry --help under
--harness-plan
|
|
--harness-review <id>
spelt --harness-review value required |
gantry <plan> |
pick the harness that runs the review role
in gantry --help under
--harness-plan
|
|
--harness-util <id>
spelt --harness-util value required |
gantry <plan> |
pick the harness that runs the utility role
in gantry --help under
--harness-plan
|
|
--harness-assistant <id>
spelt --harness-assistant value required |
gantry <plan> | pick the harness for the in-TUI Gantry Agent chat |
|
--runs
spelt --runs |
gantry stats |
emit one JSONL row per run instead of the aggregate JSON object
in gantry --help under
gantry stats
|
|
--sessions
spelt --sessions |
gantry stats |
emit one JSONL row per agent session instead of the aggregate JSON object
in gantry --help under
gantry stats
|
|
--project <path>
spelt --project value required |
gantry stats | `gantry stats` filter by project root (repeatable) |
|
--since/--until <rfc3339>
spelt --since value required |
gantry stats | `gantry stats` filter runs by first journal event timestamp |
|
--until <rfc3339>
spelt --until value required |
gantry stats |
the closing end of the first-journal-event window
in gantry --help under
--since
|
|
--kind <kind>
spelt --kind value required |
gantry stats | `gantry stats` filter by sprint, milestone, map, or other |
|
--harness <id>
spelt --harness value required |
gantry stats | `gantry stats` filter by harness |
|
--all
spelt --all, -a |
gantry stats | `gantry stats` include ineligible runs and report their reasons |
|
--no-cache
spelt --no-cache |
gantry stats | `gantry stats` bypass the folded-record cache |
|
--clear-cache
spelt --clear-cache |
gantry stats | `gantry stats` clear the folded-record cache before scanning |
|
--width <n>
spelt --width value required |
gantry stats | `gantry stats` pin the printed dashboard width (columns) |
|
--ascii
spelt --ascii |
gantry stats | `gantry stats` draw the printed dashboard without Unicode glyphs |
|
--reconcile-corpus [=<dir>]
spelt --reconcile-corpus value optional |
gantry stats | maintenance: reconcile the fleet against a replay corpus directory, defaulting to the one GANTRY_FLEET_CORPUS_DIR names not in gantry --help |
|
--reconcile-corpus-path <dir>
spelt --reconcile-corpus-path value required |
gantry stats | maintenance: the replay corpus directory to reconcile against, named outright not in gantry --help |
|
--unset
spelt --unset |
gantry config |
clear the global harness default, as `gantry config harness --unset`
in gantry --help under
gantry config
|
|
--ascii
spelt --ascii |
gantry pattern |
render the diagram as plain text, the only rendering either form supports today
in gantry --help under
gantry pattern
|
|
--detail <blocks|steps|full>
spelt --detail value required |
gantry pattern |
how much of the pattern `pattern show` draws (default: steps)
in gantry --help under
gantry pattern
|
|
--out <dir>
spelt --out value required |
gantry pattern |
where `pattern snapshots` writes (default: docs/diagrams/pattern-snapshots)
in gantry --help under
gantry pattern
|
Needs a build with devtools
The verbs
CLI verbs — 1 row
| command | arguments | what it does |
|---|---|---|
|
gantry export-reference
handled before verb detection |
<out.json> | internal maintenance helper: write the reference dataset the reference documentation is generated from |
The flags
CLI flags — 10 rows
| flag | applies to | what it does |
|---|---|---|
|
gantry --demo
spelt --demo |
any invocation | run the scripted demo in the monitor |
|
gantry --snapshot
spelt --snapshot |
any invocation | print one rendered frame and exit |
|
gantry --snapshot-slide
spelt --snapshot-slide |
any invocation | print one frame during a tail-follow slide transition |
|
gantry --snapshot-stage-log
spelt --snapshot-stage-log, --snapshot-session |
any invocation | print one frame with the stage-log modal open |
|
gantry --snapshot-reset-wait
spelt --snapshot-reset-wait |
any invocation | print one frame parked on a usage-limit reset-wait card |
|
gantry --snapshot-prompt
spelt --snapshot-prompt |
any invocation | print one frame with the prompt modal open |
|
gantry --snapshot-chat
spelt --snapshot-chat |
any invocation | print one frame with the chat pane populated |
|
gantry --snapshot-chat-maximized
spelt --snapshot-chat-maximized |
any invocation | print one frame with the chat pane maximized |
|
gantry --snapshot-chat-collapsed
spelt --snapshot-chat-collapsed |
any invocation | print one frame with the chat pane collapsed to its strip |
|
gantry --snapshot-chat-empty
spelt --snapshot-chat-empty |
any invocation | print one frame of the chat-visible empty (no-run) start state |
Needs a build with devtools and screencast
The verbs
CLI verbs — 1 row
| command | arguments | what it does |
|---|---|---|
|
gantry menu-tour-model
handled before verb detection |
[--cols <n>] [--rows <n>] [--choreography] | internal gate helper: emit the deterministic menu-tour coordinate model as JSON |
The flags
CLI flags — 3 rows
| flag | applies to | what it does |
|---|---|---|
|
--cols <n>
spelt --cols value required |
gantry menu-tour-model | terminal grid width the coordinate model is built for (default 96) |
|
--rows <n>
spelt --rows value required |
gantry menu-tour-model | terminal grid height the coordinate model is built for (default 28) |
|
--choreography
spelt --choreography |
gantry menu-tour-model | emit the pointer-choreography coordinate model instead of the plain one |
Needs a build with screencast
The verbs
CLI verbs — 10 rows
| command | arguments | what it does |
|---|---|---|
| gantry replay | <name> | play a run's recorded event tape back through the monitor (--speed <n>) |
| gantry screencast | record-timelapse <name> | record a timelapse MP4 clip (default: 1440px-high landscape at natural width; --standing keeps portrait 1080x1920; --seconds pins length, --timing supplies a profile; --resolution <1080|1440|2160|portrait|WxH>, --fit only for fixed frames) |
| gantry validate-menu-tour | <script.md> <alignment.json> <item-map.json> | validate menu-tour artifacts |
| gantry compile-menu-tour | <script.md> <alignment.json> <item-map.json> <out.json> | compile menu-tour artifacts into pointer choreography |
|
gantry tts-narrate
also gantry narrate |
<script.md> <out-basename> --audio <audio> --provider-response <json> | normalize by-hand TTS output into narration audio + alignment artifacts |
| gantry check-narration | <audio> <alignment.json> [tolerance-secs] | validate the TTS artifact pair |
| gantry backfill-journal | <name> | reconstruct one run's history.jsonl in place (by hand) |
| gantry backfill-journals | <registry-dir> | sweep a registry, reconstructing every run that needs it (skips runs already timed or backfilled; safely re-runnable) |
| gantry repair | <name> [--dry-run] | restore a run's missing/damaged recorded card text in place, reconstructed from its own briefs and retained logs |
| gantry repairs | <registry-dir> [--dry-run] | sweep a registry, repairing every damaged run (skips map-shaped, undamaged, repaired, and live runs; re-runnable) |
The flags
CLI flags — 19 rows
| flag | applies to | what it does |
|---|---|---|
|
--speed <factor>
spelt --speed value required |
gantry replay | `gantry replay` pace: recorded time compressed by <factor> (default fast-forward; 1 = real-time). Long silent gaps are clamped so playback never stalls. With --timing, defaults to real-time and scales the shaped timeline instead. |
|
--timing <profile.toml>
spelt --timing value required |
gantry <plan>, gantry replay | `gantry replay` timeline shaper: reshape the recorded run into a watchable screencast (per-stage dwell, gap compression, invented timing). Subsumes --speed; an omitted file replays raw wall-clock exactly as before. |
|
--hold-final [secs]
spelt --hold-final value optional |
gantry replay | `gantry replay` unattended filming: after the tape/journal ends, hold the final frame this long and then exit on its own (no keypress), so a screen recorder can capture it unattended. An explicit value wins over the profile's final_hold; bare uses that (or the default). Omit for interactive replay. |
|
--audio <audio>
spelt --audio value required |
gantry tts-narrate | the provider's audio file to normalize into narration audio |
|
--provider-response <json>
spelt --provider-response value required |
gantry tts-narrate | the provider's timestamped JSON response to build the alignment from |
|
--provider <id>
spelt --provider value required |
gantry tts-narrate | the TTS provider the response came from (default elevenlabs) |
|
--voice-id <id>
spelt --voice-id value required |
gantry tts-narrate | the provider voice id to record in the narration artifacts |
|
--model-id <id>
spelt --model-id value required |
gantry tts-narrate | the provider model id to record in the narration artifacts |
|
--standing
spelt --standing, --vertical, --shorts |
gantry screencast | keep the fixed portrait 1080x1920 output instead of height-pinned landscape |
|
--out <path>
spelt --out value required |
gantry screencast | write the clip to this path instead of the derived one |
|
--resolution <1080|1440|2160|portrait|WxH>
spelt --resolution value required |
gantry screencast | select another height-pinned landscape tier, portrait, or a fixed WxH frame |
|
--fit <pad|stretch>
spelt --fit value required |
gantry screencast | how a fixed frame is filled; height-pinned landscape output ignores it |
|
--seconds <n>
spelt --seconds value required |
gantry screencast | pin the clip length instead of using the adaptive profile |
|
--timing <profile.toml>
spelt --timing value required |
gantry screencast | supply the recording timing profile instead of the adaptive default |
|
--fps <n>
spelt --fps value required |
gantry screencast | recorded frame rate |
|
--hold-final <secs>
spelt --hold-final value required |
gantry screencast | hold the final frame this long at the end of the clip |
|
--nvenc
spelt --nvenc |
gantry screencast | encode with NVENC instead of the software encoder |
|
--profiles-dir <dir>
spelt --profiles-dir value required |
gantry screencast | read recording timing profiles from this directory |
|
--help
spelt --help, -h |
gantry screencast | print the record-timelapse usage string |