CLI reference

This page reflects the autodev 0.1.0 command tree. The executable's help is authoritative for the exact revision you installed:

autodev --help
autodev <command> --help
autodev <command> <subcommand> --help

There are no publish, push, deploy, or remote-merge commands.

Shared options

Repository-oriented command families generally accept --root; read surfaces generally accept --output human|json. Daemon lifecycle commands and some leaf verbs expose only the options they need, so check the installed help rather than assuming either flag is universal:

Option	Meaning
--root <ROOT>	Repository root where that command family supports it. Usually defaults to ..
`--output human	json`
-h, --help	Command help.

Top-level -V or --version prints the binary version.

Top-level --lock-wait-ms <MILLIS>, written before the subcommand, sets how long a mutating board or fleet verb waits for the repository write lock before refusing:

autodev --lock-wait-ms 1000 board create --prefix A --title "…"

Omit it and each family keeps its default — 120s for board, 10s for fleet. Either way a verb that runs out of patience exits 2 with the typed busy error naming the holder. Read verbs never take the lock, so the option does nothing for them.

Init

autodev init scaffolds a git repository: the planning tree, a commented .autodev/fleet.toml, and the .gitignore lines that keep runtime state out of git status. It is idempotent — existing files are kept, never overwritten. It accepts --root, --output, and --no-commit.

Board commands

Command	Purpose	Important arguments/options
board check	Validate files, vocabulary, contracts, and references.	Exits 1 for blocking findings.
board list	List stories.	--status <STATUS>
board get <ID>	Show one story.	—
board create	Create a backlog story.	--title; one of --id/--prefix; optional --kind, --complexity, --impact, --goal, repeated --criterion, --priority, --epic, --design, repeated --area, --term, --depends-on, --no-commit
board transition <ID> <TO>	Take a legal workflow edge.	repeated --waive <GATE> requires --reason; --no-commit
board approve <ID> --gate <GATE>	Record a human decision that a human gate passes.	--note; --no-commit
board update <ID>	Update supported frontmatter fields.	--title, --complexity, --impact, --priority, --epic, --design, --note, repeated replacement --term, --no-commit
board explain <ID>	Show transitions and current gate verdicts.	--to <STATE>
board doctor	Diagnose legacy frontmatter.	--fix applies repairs in one commit.

board approve writes an approvals entry into the story's frontmatter carrying the gate id, the actor, and any --note. The approval is durable and is spent by the transition that crosses the edge carrying that gate; re-approving the same gate replaces the standing entry. board explain names the command an unmet human gate needs in its needs field. Naming a check, evidence, or judge gate is refused, as is a gate the story's workflow does not declare. No built-in workflow declares a human gate.

Epic commands

Command	Purpose
board epic create <ID> --title <TITLE>	Create docs/epics/<id>.md; accepts --problem, --scope, repeated --non-goal, --milestone, --design, and --no-commit.
board epic list	List epics with derived child stories.
board epic show <ID>	Show one epic.

Decision commands

Command	Purpose
board decision propose --title <TITLE>	Propose the next numbered decision; accepts --context, --decision, repeated --consequence, and --no-commit.
board decision accept <ID>	Accept a proposed decision.
board decision reject <ID>	Reject a proposed decision.
board decision supersede <ID> --by <ID>	Mark an accepted decision as superseded.
board decision list	List decisions.
board decision show <ID>	Show one decision.

Decision mutations accept --no-commit.

Glossary commands

Command	Purpose
board glossary define <TERM> --definition <TEXT>	Define a kebab-case term; accepts repeated --alias, --related, --area, and --no-commit.
board glossary list	List terms.
board glossary show <TERM>	Show one term and its links.
board glossary where <TERM>	Find stories and epics that declare a term or alias.
board glossary unused	Find terms no story or epic declares.

Fleet commands

Command	Purpose	Important arguments/options
fleet tick	Run one reconciler pass.	—
fleet drive	Run ticks until quiet or bounded.	--ticks <N> defaults to 30; --interval <SECONDS> defaults to 5; --loop keeps serving until stopped and is refused alongside an explicit --ticks.
fleet status	Show waves, workers, recent events, pause, and drain state.	—
fleet disk	Measure build caches/worktrees against the declared disk floor.	—
fleet doctor	Report persisted waves the reconciler cannot act on.	Exits 1 when any exist.
fleet coordinate	Run the coordinator loop as a process outside the drive.	--interval <SECONDS> defaults to 10; optional --cycles <N> bounds it.
fleet park <WAVE>	Halt a wave and cancel its workers while its stories stay held.	required --reason
fleet unpark <WAVE>	Reopen a parked wave and restore one attempt, or defer when its areas are held elsewhere.	—
fleet retire <WAVE>	Make a wave terminal and release its stories.	required --reason
fleet pause	Stop new dispatch and optionally wait for owned turns to drain.	required --reason; --principal defaults to operator; optional --if-event-seq <N> compare-before-write guard (required for coordinator turns); optional --wait <SECONDS>
fleet resume	Resume dispatch.	--principal defaults to operator.
fleet shutdown	Freeze every external-command lane, wait, then TERM/KILL overdue groups.	required --reason; --wait <SECONDS> defaults to 300; --principal defaults to operator.
fleet start	Clear durable shutdown and resume from command checkpoints.	--principal defaults to operator; does not clear fleet pause.
fleet drained	Report whether this drive owns any turn.	Exits 0 when it owns none.

There is no fleet cancel. Parking does not release stories; retiring does.

fleet unpark has two outcomes, not one. A wave must re-earn the areas it claims before it re-enters the loop: if another live wave holds one of them, the wave stays parked and the answer names the area, the holding wave, and the story that pinned it. Nothing is written in that case — no reopen, no restored attempt — so a deferral leaves no trace of a reopen that did not happen. The wave re-enters when the holding claim is released.

fleet park, fleet unpark, and fleet retire emit the wave state under --output json, as one document with verb, wave, and found, plus — when the wave was found — the flattened wave state (a state discriminator such as parked, reopened, or cancelled, alongside that variant's fields such as reason) and attempts_remaining, attempts_limit, revision.

An unpark deferral is not visible in JSON

The deferral sentence is printed only under --output human. Because a deferral writes nothing, fleet unpark --output json reports "state": "parked" with the wave's original park reason and never names the holder — indistinguishable from an unpark that was never attempted. Read the human output, or the wave's park reason after the next tick, to tell the two apart.

Metrics commands

Command	Purpose	Options
metrics stories	Per-story time in each planning status.	--epic <ID>
metrics epics	Per-epic throughput, median cycle time, and open/total counts.	—
metrics forecast	Estimated drain time from measured delivery rate.	—
metrics waves	Wave phase durations, attempts, and park reasons.	—
metrics fleet	Tick cadence and evidence/judge rates.	—
metrics usage	Tokens and cost by model, story, or wave.	`--by model
metrics orientation	Tool calls before the first worker write.	—
metrics predictions	Predicted filesets scored against delivered writes.	—

Workflow commands

autodev workflow inspects coordinator workflow graphs: what is installed, and what one resolves to once the repository's .autodev/coordinator.yaml is applied over the built-in.

Command	Purpose
workflow list	The installed coordinator workflows, built-in and repository-configured.
workflow show <ID>	Print one resolved workflow graph with every default made explicit, e.g. coordinator.tick.

These read coordinator workflows. They are a different surface from the story workflows configured in .autodev/workflows.toml, which are reported by board explain.

Diff

autodev diff <SELECTOR> resolves a planning or runtime entity to its observed Git change set. The selector is one of commit/<sha>, worker/<id>, wave/<id>, story/<id>, epic/<id>, milestone/<id>, or release/<from>..<to>. Output form is --stat (the default), --name-only, or --patch.

Event commands

autodev events reads the recorded event log: what happened, since when, in sequence. It is read-only, takes no repository write lock, and therefore answers while a drive is mid-tick. Its findings do not set exit 1.

Option	Meaning
--since <RFC3339>	Only events recorded at or after this instant. Inclusive, so the event recorded exactly then is part of the answer.
--after <SEQ>	Only events above this sequence number. Strictly greater, so the last sequence you saw is the cursor to pass back.
--kind <KIND>	Repeatable. The dotted event kind, worker.turn-completed; the bare tag the stored record carries, turn-completed, selects the same events. Rendered output always uses the dotted name.
--exclude-kind <KIND>	Repeatable complement of --kind; useful for watching every new event except a caller's own noise.
--fail-if-empty	Still render the feed, but exit non-zero when nothing matched.
--limit <N>	Return at most N events, oldest first.

Two properties the output guarantees:

• a --kind that selected no event in the range read is named in the answer (kinds_selecting_nothing in JSON), rather than returned as an empty result indistinguishable from a quiet fleet;
• a bounded answer says so. With --limit, JSON carries bounded, matched, returned, omitted, and next_after; the human rendering says bounded by --limit <N>, <M> omitted; resume with --after <SEQ>. Without --limit it says complete for this filter.

A repository with no fleet store reports present: false and no events, which is not the same claim as a fleet that did nothing.

Conversations

autodev conversation is the durable request-and-answer surface used by the shell, the operator workspace, and agent turns.

Command	Purpose	Important arguments/options
conversation say [TEXT]...	Record a request verbatim.	--profile <ID> defaults to coordinator; --id <ID> supplies the caller's idempotency key.
conversation answer --request <ID> [TEXT]...	Record an outcome for one named request.	--outcome accepts answered, refused, or waiting-human; --profile <ID>
conversation show	Read a conversation and its unanswered queue.	--profile <ID>; --unanswered; --limit <N>

Omitting --id from conversation say asks the store to mint one. A retry without reusing that id records a second request; this is explicit request semantics, not automatic deduplication.

Daemon and workspace commands

The central daemon is an optional store owner for registered workspaces. One process serves the machine JSON API on 7788 and the embedded browser client on 7777 through separate listeners.

Command	Purpose	Important arguments/options
daemon start	Start the central store, client listeners, and registered-workspace drives.	--address <ADDR> defaults to 127.0.0.1:7788; --client-address <ADDR> defaults to 127.0.0.1:7777; --single-user; --no-drive; machine and act token options
daemon status	Report whether the daemon is running, its version, endpoint, and workspace count.	`--output human
daemon stop	Report the drain floor and stop sequence.	Advisory in 0.1.0; does not signal the daemon.
daemon restart	Report the safe replacement sequence.	Advisory in 0.1.0; does not signal or re-exec.
daemon openapi	Print the generated /v1 OpenAPI document.	--write writes docs/api/openapi.json; optional --root selects that source tree.
workspace register [ROOT]	Register a Git repository with the daemon.	--id <ID>; --import; `--output human
workspace list	List registered workspaces and legacy-history state.	`--output human
workspace import [ROOT]	Carry a local .autodev/fleet.sqlite into the registered workspace store and verify its counts.	`--output human

See Central daemon and workspaces before importing an existing fleet or replacing a running binary.

Other commands

autodev retro mines transcripts, receipts, and events for typed friction. It is read-only and its findings do not set exit 1.

autodev daemon start binds the machine API and the operator client, and drives every registered workspace. autodev serve starts the client alone for one more release, but is no longer the supported ordinary console path. Important daemon start options are:

Option	Meaning
--address <ADDR>	Machine API address, default 127.0.0.1:7788.
--client-address <ADDR>	Operator client address, default 127.0.0.1:7777.
--token / --token-file	Machine bearer credential; generated and recorded when omitted.
--act-token <TOKEN>	Grants mutation rights to clients presenting the token. Without it, all clients are read-only.
--single-user	Grants act to every loopback client without asking for a token.
--no-drive	Serves both listeners without driving registered workspaces.

Exit behavior

The CLI library defines these broad outcomes:

• 0: the invocation completed without a gating finding;
• 1: a check or state query found the condition it documents, such as blocking board findings, malformed waves, or an undrained wait;
• 2: the invocation itself failed and the binary printed error: ....

Individual help text documents important exceptions. In particular, retro and events findings are informational and return 0.

A mutation refused because the repository write lock was busy also exits 2, but with --output json it prints a typed envelope on stdout first:

{
  "refusal": "write-lock-busy",
  "verb": "fleet park",
  "retryable": true,
  "lock": "repository write lock",
  "holder": { "pid": 41234, "operation": "fleet drive" },
  "waited_seconds": 10,
  "detail": "repository write lock is busy; held by `fleet drive` (pid 41234)"
}

retryable is the field to branch on: a refusal on the merits carries no such envelope, so "try again in a second" and "this will never work" are distinguishable without parsing prose. A lock that could not be read at all is the sibling case — "refusal": "write-lock-unreadable" with retryable false and holder null.

waited_seconds is the patience the verb was given, not the elapsed wall time it actually spent.