Command line
Every verb the binary answers to and every flag it parses, with the builds that have them.
Day to day
| command | arguments | what it does |
|---|---|---|
| gantry | plan.md | build a file, directory, or inline plan via milestones (small plans collapse to one pass) |
| gantry | plan.md --pattern my_custom_pattern.toml | run a discoverable pattern with typed inputs |
| gantry list | — | active runs by name, state, and progress (alias: ls; -v/--verbose adds finished) |
| gantry status | — | show a run's details and its ledger |
| gantry enter | — | open a shell in a run's worktree and write a GANTRY-STATUS.md guide (defaults to the lone active run) |
| gantry resume | — | resume a run by name; unnamed resumes the lone run or opens a TTY picker (aliases: --resume [<name>], -r [<name>]; newest: --last, --continue, -c) |
The verbs
CLI verbs — 34 rows
of 36 exported from src/engine/cli_specification.rs
| command | arguments | what it does |
|---|---|---|
| gantry agents | init | install the project orientation pointer |
|
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 replay | <name> | play a run's recorded event tape back through the monitor (--speed <n>) |
| gantry pattern | show <name> --ascii [--detail blocks|steps|full] [--width <columns>] | render a static pattern diagram |
| gantry pattern | snapshots --ascii [--out <dir>] [--width <columns>] | write shipped pattern diagram review snapshots |
| gantry help | [<verb>] | print the usage text or one verb's usage row |
| 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 default prompts, patterns, and docs (--yes to skip the prompt) |
| gantry config | harness <role> <id> | set the global harness default for one role (plan, build, review, util) not in gantry --help |
| gantry config | model <role> <model> | pin the model one role's harness is invoked with (plan, build, review, util) not in gantry --help |
| 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 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 backfill-record | <name> [--dry-run] | preserve one finished run's post-completion record tail in its run book |
| gantry backfill-records | <registry-dir> [--dry-run] | sweep a registry, preserving post-completion record tails (skips complete, active, and live runs; safely re-runnable) |
| gantry extract-book | <name>|--all [--untrack] [--yes] | extract legacy committed run records into run books; --untrack reports tracked legacy paths unless --yes applies |
| gantry repair | <name> [--dry-run] | restore damaged recorded card text and report lost merge candidates |
| gantry repairs | <registry-dir> [--dry-run] | sweep a registry for damaged run records and lost merge candidates |
|
gantry assistant
also gantry agent handled before verb detection |
[--headless] <message>… | diagnostic Gantry Assistant conversation in a git repository: one turn per quoted message (legacy alias: agent) not in gantry --help |
|
gantry external-agent
handled before verb detection |
[harness-id] | diagnostic for the blocker investigation terminal: prints the window tier, or the inline or refusal decision, without spawning one 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 67 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 assistant | build a file, directory, or inline plan via milestones (small plans collapse to one pass) |
| -p, --print, --headless | gantry <plan>, gantry replay, gantry assistant | print non-interactive plain lines instead of opening the TUI |
|
--json
spelt --json |
gantry <plan>, gantry list, gantry status, gantry stats | with --headless/-p/--print, emit newline-delimited JSON event records; with `gantry list` or `gantry status <name>`, emit this repository's runs as newline-delimited run 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 |
force the teardown through an unclean or incomplete stop, after verifying the surviving processes by hand
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 extract-book, gantry config, gantry agents |
skip the confirmation prompt
in gantry --help under
--clean, gantry prune, gantry purge, gantry worktrees, gantry build-directories, gantry merge, gantry config, gantry agents, gantry extract-book
|
|
--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, gantry extract-book |
on a reclamation verb, act on every eligible run instead of one named run; on `gantry list`, show finished runs too
in gantry --help under
gantry prune, gantry purge, gantry worktrees, gantry build-directories, gantry extract-book
|
|
--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, gantry backfill-record, gantry backfill-records |
report what would change without changing anything
in gantry --help under
gantry prune, gantry purge, gantry worktrees, gantry build-directories, gantry repair, gantry repairs, gantry backfill-record, gantry backfill-records
|
|
--untrack
spelt --untrack |
gantry extract-book |
report tracked legacy record paths for removal from the primary repository; apply only with --yes
in gantry --help under
gantry extract-book
|
|
--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
|
|
--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. |
|
--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: playback defaults to real-time and --speed scales the shaped timeline instead. An omitted file replays raw wall-clock exactly as before. |
|
--target-length <secs>
spelt --target-length value required |
gantry replay | `gantry replay` clip length: scale the shaped timeline toward <secs> in total, overriding the timing profile's own target_length. Wins over --adaptive, and has no effect without --timing — there is no shaped timeline to scale. |
|
--adaptive
spelt --adaptive |
gantry replay | `gantry replay` adaptive clip length: derive the target length from this run's own task count (the profile's seconds_per_unit per task, clamped by target_min/target_max) instead of its pinned target_length. Needs --timing; a profile that configures no seconds_per_unit keeps its pinned length. |
|
--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. |
|
--map <source>
spelt --map value required |
gantry <plan> | run an explicit Map roster from a source document |
|
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 with --param against entry parameters |
|
--merge <name|file.toml>
spelt --merge value required |
gantry <plan> | select the merge reconciliation pattern; `gantry merge` remains the partial-merge verb |
|
--param <name> <value>
spelt --param value required |
gantry <plan> | bind one declared entry pattern parameter by name |
|
gantry --until goal.md
spelt --until value required |
gantry <plan> | recursively build until the acceptance check passes |
| --until <goal.md> | gantry <plan> | start an until run: check, build one gap plan, then recurse |
|
--max-cycles <N>
spelt --max-cycles value required |
gantry <plan> | retired: `--until` rejects it, and recursion ends when the acceptance check passes or the gap planner reports no work not in gantry --help |
|
--
spelt -- |
gantry <plan> | end Gantry's own option parsing, so a run operand may begin with `-`; the marker and everything after it pass through untouched 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 `util` 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 Assistant 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 bound of that window
in gantry --help under
--since
|
|
--kind <kind>
spelt --kind value required |
gantry stats | `gantry stats` filter by task, 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 |
|
--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
|
|
--width <columns>
spelt --width value required |
gantry pattern |
column budget a pattern diagram is laid out to; `pattern show` defaults to the terminal and falls back to 51, `pattern snapshots` always uses 51
in gantry --help under
gantry pattern
|
Needs a build with devtools
The verbs
CLI verbs — 2 rows
| command | arguments | what it does |
|---|---|---|
|
gantry export-reference
handled before verb detection |
<out.json> | write the reference dataset the documentation pages render |
|
gantry export-reference-markdown
handled before verb detection |
<manual-dir> [web-manual-dir] | write the generated markdown source documents for dataset-backed documentation pages |
The flags
CLI flags — 12 rows
| flag | applies to | what it does |
|---|---|---|
|
gantry --tour
spelt --tour |
any invocation | run the mock engine's 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 |
|
--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 |
|
--reconcile-corpus-path <dir>
spelt --reconcile-corpus-path value required |
gantry stats | maintenance: the replay corpus directory to reconcile against, named outright |
How a run name resolves
Run operation reference contract — 2 sets exported from
src/engine/reference_dataset.rs
| ambiguity reports candidates | description | id | precedence | primary keys win ties | relation | unique match required |
|---|---|---|---|---|---|---|
| true | A query matching one run name exactly resolves before prefix or substring matching. | exact_match | 1 | true | equals | true |
| true | A query matching exactly one run by prefix resolves after exact matching finds no run. | unique_prefix | 2 | true | starts_with | true |
| true | A query matching exactly one run by substring resolves after exact and prefix matching find no run. | unique_substring | 3 | true | contains | true |
| true | An ambiguous query returns the matching runs' display names so the caller can report candidates. | ambiguity_candidates | 4 | true | multiple_matches_in_first_matching_tier | false |
| consequence | id | mechanism | subject |
|---|---|---|---|
| A second engine can see that a live owner already holds the run and must not drive the same run concurrently. | one_owner_lock | Each run owns one `run.pid` file protected by an advisory `flock`; an acquiring engine records its pid and process identity while it holds the lock. | one-owner run lock |
| The durable run record remains resumable instead of becoming a broken live run. | stale_owner_record | A dead owner releases the kernel lock and leaves only a stale owner record, which ownership readers report as unowned. | lost terminal or crashed process |