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

flowctl init
flowctl specs
flowctl tasks --spec fn-1
flowctl ready --spec fn-1
flowctl show fn-1.2
flowctl start fn-1.2
flowctl done fn-1.2 --summary-file summary.md --evidence-json evidence.json
flowctl validate --all

Spec commands

flowctl spec create --title "Add OAuth" --json
flowctl spec set-plan fn-1 --file spec.md --json
flowctl spec set-branch fn-1 --branch fn-1-add-oauth --json
flowctl spec close fn-1 --json

State layout

.flow/
├── meta.json
├── specs/
├── tasks/
├── memory/
├── bin/
└── usage.md

Agents should use flowctl for writes instead of hand-editing state JSON.

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

Agent-facing commands generally follow this sequence:

flowctl ready --spec fn-1 --json
flowctl start fn-1.2 --json
flowctl done fn-1.2 --summary-file summary.md --evidence-json evidence.json
flowctl validate --all

Direct CLI usage is useful for automation, but human docs should keep teaching the slash-command workflow first.