CLI Reference
flowctl is the deterministic CLI for .flow/ state.
Most users should use /flow-next:* commands. Use flowctl when debugging state, scripting CI, building integrations, or inspecting what the skills wrote.
Common commands
Section titled “Common commands”flowctl initflowctl specsflowctl tasks --spec fn-1flowctl ready --spec fn-1flowctl show fn-1.2flowctl start fn-1.2flowctl done fn-1.2 --summary-file summary.md --evidence-json evidence.jsonflowctl validate --allSpec commands
Section titled “Spec commands”flowctl spec create --title "Add OAuth" --jsonflowctl spec set-plan fn-1 --file spec.md --jsonflowctl spec set-branch fn-1 --branch fn-1-add-oauth --jsonflowctl spec close fn-1 --jsonflowctl spec ready fn-1 --json # mark ready for execution (human-owned gate, 1.12.0+)flowctl spec unready fn-1 --json # back to draftspec ready / spec unready toggle the spec’s readiness flag — the human-owned “complete enough to hand to an agent” gate. Both are idempotent (no write, no updated_at bump when the flag already matches; --json reports "changed"). The flag is lazy on disk (written only after a toggle; absent reads false) but every JSON read surface (show, specs, list) emits an explicit "ready": <bool>, and ready specs carry a [ready] badge in listings. Orthogonal to status — a ready spec stays open through planning and work. With tracker.readyState configured the tracker is authoritative and overwrites local toggles on sync — see Tracker Sync.
State layout
Section titled “State layout”.flow/├── meta.json├── specs/├── tasks/├── memory/├── bin/└── usage.mdAgents should use flowctl for writes instead of hand-editing state JSON.
CLI responsibility
Section titled “CLI responsibility”| Responsibility | Why it lives in flowctl |
|---|---|
| ID allocation | Must be deterministic and merge-safe |
| State transitions | Must be machine-readable |
| Validation | Must run in CI and local shells |
| Receipts | Must survive chat context |
| Migration | Must preserve repo-local state |
Judgment stays in the host agent. flowctl should not decide whether a spec is good, whether an architecture is right, or whether a finding is product-important.
Agent usage pattern
Section titled “Agent usage pattern”Agent-facing commands generally follow this sequence:
flowctl ready --spec fn-1 --jsonflowctl start fn-1.2 --jsonflowctl done fn-1.2 --summary-file summary.md --evidence-json evidence.jsonflowctl validate --allDirect CLI usage is useful for automation, but human docs should keep teaching the slash-command workflow first.