Skip to content

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.

This page covers the verbs you are most likely to script or inspect. flowctl --help lists every verb, flowctl <verb> --help (and flowctl <verb> <subverb> --help) prints its exact options, and flowctl usage prints the agent guide bundled with the installed plugin. The review dispatch verbs (flowctl codex|copilot|cursor|claude ...) and the bookkeeping verbs the skills call between review rounds are listed there and not repeated here.

Terminal window
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 start fn-1.2 --reclaim # resume your own in_progress task; since 5.5.0 a plain start on it refuses
flowctl done fn-1.2 --summary-file summary.md --evidence-json evidence.json
# evidence.json: {"commits": ["<sha>"], "tests": ["<command>"], "prs": []}
flowctl done fn-1.2 --range BASE..HEAD --test "python3 -m unittest" --summary-file - --json # 6.1.0: commits from a contiguous range, summary on stdin
flowctl validate --all

Editing tasks and their order:

Terminal window
flowctl start fn-1.2 --note "prior session ended" # claim note, recorded with the claim
flowctl task set-description fn-1.2 --file desc.md # '-' reads stdin
flowctl task set-acceptance fn-1.2 --file acceptance.md
flowctl dep add fn-1.3 fn-1.2 # fn-1.3 depends on fn-1.2
flowctl task reset fn-1.2 # back to todo, from done or blocked
flowctl task reset fn-1.2 --cascade # also reset the tasks in the same spec that depend on it
flowctl validate --spec fn-1 --coverage --json # adds the requirement coverage table

validate --coverage (with --spec) adds requirement_coverage, a markdown table rendered from the tasks’ satisfies lists. Plan uses it to replace the spec’s ## Requirement coverage table. A task that satisfies an R-ID the spec does not have, and an R-ID no task satisfies, are warnings.

done checks its evidence (6.1.0). Evidence must carry at least one of commits, tests, or prs; other keys besides base_commit, files, and files_touched print a warning and are not rendered. --range BASE..HEAD derives commits and base_commit from the range and fails naming any unreachable SHA; repeat --test for several commands. Interleaved task histories keep explicit evidence lists. With planSync.enabled not true, done appends the stage: plan-sync - skipped(config: planSync.enabled != true) line to the summary itself.

show <spec> --json is smaller (6.1.0). It omits the review-attempt and tracker ledgers. Read them with flowctl review-rounds attempts <spec> --kind plan|impl --review-type plan|impl|completion and flowctl sync get-state <spec>. Since 9.17.0 it carries plan_review_drift: the paths the spec cites that changed since the commit its SHIP plan review saw, while no task has started, and an empty list when none did or the check does not apply (A SHIP whose cited files changed). Since 9.5.1 it carries completion_review_pending: true when a completion review is configured for the spec (the spec’s own review setting, then FLOW_REVIEW_BACKEND, then review.backend) and its status is not ship or not_required. make-pr leaves such a spec open.

Terminal window
flowctl specs --refs [--fetch] [--json]

Indexes every spec on the base ref (origin/HEAD, then origin/main, main, origin/master, master), on local branches and on remote-tracking refs. Plain flowctl specs is unchanged and still lists only the checkout. Without --fetch the command is offline and writes nothing; --fetch prune-fetches origin first, and a failed fetch still indexes the local refs (fetched: false, with git’s message in fetch_error, exit 0).

Each branch copy whose body differs from base is classified:

  • live - merging the branch into base would change the spec body. conflict: true when that merge conflicts. Squash merges are handled: a squash-merged branch’s changes are already in base.
  • stale - it carries nothing unmerged: an older copy, a merged copy, or a copy of a spec deleted on base.
{
"success": true,
"base": "refs/remotes/origin/main",
"fetched": false,
"fetch_error": null,
"refs_scanned": 85,
"summary": {
"branch_only": ["fn-12-login-flow"],
"ahead_of_base": ["fn-9-export"],
"concurrent_edits": ["fn-9-export"],
"would_conflict": [],
"local_branches_upstream_gone": ["refs/heads/old-feature"]
},
"specs": [
{
"id": "fn-9-export",
"title": "Export",
"status": "open",
"on_base": true,
"live": [
{"ref": "refs/remotes/origin/feat/export", "tip_date": "2026-10-06", "conflict": false},
{"ref": "refs/remotes/origin/feat/export-v2", "tip_date": "2026-10-05", "conflict": false}
],
"stale_refs": ["refs/remotes/origin/fn-3-old-branch"],
"tracker": null
}
]
}

specs covers every spec id seen on base or any scanned ref. Title, status and tracker come from base’s sidecar when the spec is on base, otherwise from the first live ref in sorted order. With no base ref the command fails with success: false, naming the refs it tried, and exits 1.

Consumers: an older flowctl rejects the flag with exit 2 and unrecognized arguments: --refs; treat that as “not supported” and fall back to plain flowctl specs. Hygiene and team shapes: For teams.

Terminal window
flowctl specs --refs --tracker-id <id> [--fetch] [--json]

Lists only the specs whose JSON links the durable tracker id <id>: in the checkout, committed or not, and on every local branch and remote-tracking ref. It reads each ref’s spec JSON rather than its body, so it finds a link that only a JSON change on a branch carries, and a spec already on base. Output is {tracker_id, fetched, fetch_error, linked: [{id, checkout, refs[]}]}. A spec JSON it cannot read or parse, such as a missing blob in a partial clone, fails the command instead of reading as “not linked”. The flag needs --refs. flow --auto --from-issue uses it to find a spec that already links the issue.

Deterministic store for optional pre-capture decision-map discovery. Skill page: Chart.

Terminal window
flowctl chart create --title "Multi-tenant billing" --outcome "..." --initial-map-file map.json --json
flowctl chart show fn-140 --json
flowctl chart list --json
flowctl chart frontier fn-140 --json
flowctl chart add-decision fn-140 --title "Research provider limits" --type research --json
flowctl chart claim fn-140.D1 --json
flowctl chart attach-asset fn-140.D3 --asset-file asset.json --json
flowctl chart resolve fn-140.D1 --answer-file answer.md --sharpen-file sharpen.json --json
flowctl chart resolve fn-140.D3 --answer-file answer.md --supersedes D2 --json
flowctl chart out-of-scope fn-140.D4 --reason "Beyond outcome" --json
flowctl chart release-claim fn-140.D1 --json
flowctl chart release-claim fn-140.D1 --break-stale --reason "owner session lost" --json
flowctl chart park-question fn-140 --body-file q.md --json
flowctl chart remove-question fn-140 --question <key> --json
flowctl chart wire-decision fn-140.D5 --blocked-by D1 --depends-on D2 --json
flowctl chart briefing fn-140 --proposal-file proposal.json --json
flowctl chart locate "https://linear.app/.../stored-url" --json
flowctl chart link-spec fn-140 --briefing B1 --spec fn-141 --decisions fn-140.D1,fn-140.D2 --json
flowctl chart abandon fn-140 --reason "deprioritized" --json
flowctl chart reopen fn-140 --reason "new constraint" --json
ConcernContract
Envelope{success, schema_version:1, command, result|error}
Error classesnot_found, conflict, invalid_state, invalid_graph, stale_claim, validation, io
Size ceilingchart.maxDecisions (default 12); override only via --force-size --reason after consent
Stale claimschart.claimStaleAfter hours (default 24); --break-stale always audited
LocateLocal provenance ledger only - no network, no title matching
Tracker projectionWhen bridge active and tracker.charts=on; local commit first; remote failure never rolls back

Decision types: research|probe|eval|prototype|interview|task. Attendance derived for the first five; task requires --attendance attended|unattended.

Terminal window
flowctl spec create --title "Add OAuth" --branch fn-1-add-oauth --json
flowctl spec create --title "Add OAuth" --plan-file plan.md --json # one-shot create+set-plan (--plan - reads stdin)
flowctl spec create --title "Add OAuth" --tracker-parent PROJ-12 --json # 9.13.0: the parent issue its tracker issue is created under
flowctl spec skeleton [--json] # print the scaffold spec create writes: templates/spec.md via SPEC.md -> spec.md -> bundled (frontmatter stripped)
flowctl task create --spec fn-1 --from-json tasks.json --json # bulk tasks: one call, one lock, all-or-nothing
flowctl task create --spec fn-1 --title "implement this spec" --require-empty-spec --json # mint only while the spec has zero tasks
flowctl spec set-plan fn-1 --file spec.md --json
flowctl spec set-branch fn-1 --branch fn-1-new-name --json # rename an existing spec's branch
flowctl spec chain fn-2 --json # read-only: may this dependent spec start now, and on which parent's branch
flowctl spec close fn-1 --json # close the spec and write every task's final status; the caller commits modified_paths
flowctl spec close fn-1 --retire superseded --by fn-7 --json # close a spec that ends without being built (superseded|moot|delivered-elsewhere)
flowctl spec closed-in-range --base origin/main --json # read-only: which specs does this branch close
flowctl spec ready fn-1 --json # mark ready for execution (the consent gate, 1.12.0+)
flowctl spec unready fn-1 --json # back to draft
flowctl spec set-no-plan fn-1 --json # record direct execution consent on a zero-task spec (refused once tasks exist)
flowctl spec clear-no-plan fn-1 --json # clear the field (always allowed)
flowctl spec set-completion-review-status fn-1 --status ship --if-current needs_work --json # compare-and-set

spec create --tracker-parent <identifier> (9.13.0) records tracker.parent on the new spec: the parent issue, as the tracker displays it, that the spec’s tracker issue is created under. It works with the flow-first and the --tracker-first form. flow-next reads it only when it creates that issue and never sends it again, and an empty value is refused. What each tracker accepts is in Parent issue at creation.

spec set-completion-review-status --if-current <status> writes only when the current completion-review status equals <status>, checked under the spec’s lock. On a mismatch it writes nothing and --json reports written: false. Statuses are ship, needs_work, needs_human, unknown and not_required.

A cold session orients with flowctl brief - session-scope sibling of the task-scope anchor bundle. One pure-read call renders open specs (one-line goals), actionable tasks with claim state, the last five completions with evidence flags, the memory index, and go-deeper pointers, deterministically capped at ~2k tokens with explicit truncation markers (--full lifts the cap, --json is the machine form with identical retained items). No git state, no writes: brief is .flow/-only, so identical state always renders identical bytes.

Terminal window
flowctl brief # cold-session orientation, <=2k tokens
flowctl brief --full # same sections, no truncation
flowctl brief --json # machine form, per-section truncated flags
flowctl anchor fn-1.2 # one task's bundle as the worker reads it (--md, the default)
flowctl anchor fn-1.2 --json # machine form: sections and dependencies

The ceremony fast path. A spec with a plan plus its full task set lands in two calls instead of about eight, with the same validation, atomicity, and receipts as the granular verbs. --from-json takes a non-empty array of {title, description?, acceptance?, touches?, satisfies?, deps?, priority?}, where deps entries are task ids or 1-based indexes of earlier entries. Since 6.1.0 description_file and acceptance_file may replace the inline strings (paths resolve relative to the JSON file, or the current directory for stdin), and touches is a single line rendered as the task’s Touches line. It rejects the whole batch on any invalid item with zero writes, names every invalid item and the allowed keys in one error, and returns the created ids in input order. The granular verbs remain the editing path. --require-empty-spec refuses, naming the existing task, when the spec already has one; the check runs under the same per-spec lock that allocates ids, so exactly one of N concurrent creates wins. That is the atomic mint behind the no-plan route.

spec ready / spec unready toggle the readiness flag, which you set (a flow --goal run also sets it for a child spec it minted). Both are idempotent (no write and no updated_at bump when the flag already matches; --json reports "changed"). The flag is lazy on disk, so an absent value reads false, but every JSON read surface emits an explicit "ready": <bool> and ready specs carry a [ready] badge in listings. It is orthogonal to status. With tracker.readyState configured the tracker is authoritative and overwrites local toggles on sync (Tracker sync).

spec set-no-plan / spec clear-no-plan toggle the sibling human-owned no_plan boolean, the durable “skip decomposition” consent behind the no-plan route. Same lazy contract as ready: idempotent toggles (--json reports "changed"), absent reads false, and every JSON read surface emits an explicit "no_plan": <bool> (noPlan on ready --all rows). Setting is refused once the spec has any tasks, because a planned spec routes through its tasks; clearing is always allowed (stale-field cleanup). The field is flow-local and never tracker-projected. Two consumers read it: flow --auto classifies a marked zero-task spec straight to the work dispatch, and on a ready zero-task spec with no recorded route it applies the plan-versus-no-plan rule and records the result with these two verbs before any mint; work honors the field as the explicit no-plan instruction.

spec add-dep / spec rm-dep record and remove a dependency between specs (flowctl spec add-dep fn-2 fn-1: fn-2 depends on fn-1). Since 9.7.0 add-dep refuses a dependency that would close a loop, a spec depending on itself included. It writes nothing, exits 1 and names the loop in dependency order:

{"success": false, "error": "Dependency cycle: fn-3 -> fn-1 -> fn-2 -> fn-3", "code": "dependency_cycle", "cycle": ["fn-3", "fn-1", "fn-2", "fn-3"]}

validate --all reports every loop already on disk once, as a Spec dependency cycle: <path> error and in spec_cycles, and fails. Deps shows why each stuck spec cannot start.

spec chain is the read-only chain-eligibility predicate for a dependent spec and the one owner of the rule every consumer applies: flow --auto selection in ready and backlog mode, attended flow’s next-item pick, /flow-next:work at branch creation, and flowctl’s own task-admission gate (ready --spec, next, ready --all). It returns {spec, eligible, parent, parent_branch, parent_branch_on_remote, reason}. eligible is true when every dependency is landed (parent is null, reason is no open dependency, no remote read), or when exactly one dependency is unlanded with all of its tasks done, every other dependency is landed, that parent’s branch exists on origin, and no other unlanded spec is already chained on the same parent. A spec now closes on its pull request branch before the merge, so done alone does not mean landed. A locally closed dependency counts as landed when the default base records it as closed. Failing that, flowctl reads the dependency’s spec at the merge-base of its branch and HEAD: a close recorded there means this branch is stacked on unmerged work, and the dependency stays chained. With no close in the shared history it counts as landed, which covers a dependency squash-merged into a non-default integration branch, a deleted branch, and a spec with no recorded branch. A true merge onto a non-default base conservatively stays unlanded. These reads are local and never fetch. Otherwise reason is one of dependency <id> in progress, two open parents: <id>, <id>; chains are linear, parent branch <b> not on origin; push it or land the parent first, dependency <id> closed locally but not recorded at <base>; dependency branch <ref> is in this branch's history; fetch the base or land it, parent <id> already chained by <sibling-id>, base query failed: <error>, or remote query failed: <first stderr line> (parent_branch_on_remote: null; a failed query is never reported as an absent branch). At most one git ls-remote --heads origin per invocation, none when the spec has no dependencies, and never gh. Exit 0 on any evaluation; exit 2 when the spec or a named dependency does not exist. The task-admission gate treats the chain parent as satisfied and still empties the frontier on every other not-done dependency; task-level depends_on is unchanged. Consumers: work, make-pr, land.

spec close closes the spec and writes each task’s final status: done into its tracked JSON file, so a fresh clone reads the finished state. It refuses, before any file changes, when a task is incomplete. It writes files and commits nothing: --json returns modified_paths, naming the spec file and every task file it rewrote, and the caller commits exactly those. make-pr does this as the last commit before the pull request opens. Creating or starting a follow-up task reopens a closed spec and reports the spec file the same way.

spec close --retire <superseded|moot|delivered-elsewhere> [--by <spec-or-PR>]... closes a spec that ends without its own implementation: another spec superseded it, it became moot, or it shipped under other work. The spec records retired: {reason, by}, every task that never ran reads retired instead of done, and completion review records not_required, which every close and merge gate accepts. next stops routing to the spec, show, specs and list print retired: <reason> by <refs>, and land and make-pr count a pull request that retires a task-less spec as carrying it. An unknown reason is refused with the accepted list, --by without --retire is refused, and retiring a closed spec is refused. Creating a task reopens the spec and re-arms completion review.

spec set-plan overwrites the spec body. When the body changes and the plan review reads ship, the status becomes stale (reported as plan_review_stale: true), so work stops and flow runs plan-review again first. Anything that reads plan_review_status should treat stale like needs_work; spec set-plan-review-status accepts it too.

spec closed-in-range --base <ref> lists the specs a branch closes: done at HEAD, absent or not done at the merge base with <ref>, and with task files the range touches. A close that changes only the spec record is excluded, and so is a sibling whose close belongs to the history of its own still-existing branch. Text output prints one id per line; --json returns {"spec_ids": [...]} in the same order. It reads local committed objects only and never writes or fetches. make-pr uses it to write one body for a branch that closes several specs, hosting on the last id when no spec names the branch.

pr-cognitive-aid validates, stores, selects and renders the one object behind a make-pr body.

Terminal window
flowctl pr-cognitive-aid validate --file aid.json [--json] # read-only
flowctl pr-cognitive-aid write <spec-id> --file aid.json --base-sha <sha> --head-sha <sha> [--json]
flowctl pr-cognitive-aid current <spec-id> --base-sha <sha> --head-sha <sha> [--json]
flowctl pr-cognitive-aid render <spec-id> --base-sha <sha> --head-sha <sha>
flowctl pr-cognitive-aid render --file aid.json
  • render emits one briefing for every diff size. The sections are Why, Review focus, Needs you, Shape, What changes for a user or operator, Reading order, Tradeoffs and Verified, and an empty section disappears. There is no compact or full form, no size threshold, no body line budget and no forge-visible file list or totals. Each review step names its first described file as the place to start; mechanical and generated files close the reading order in one safe-to-skim line. Proof cells with outcome fail or unverified render unticked under Needs you with their note; pass cells are ticked under Verified, and a cell with no outcome is a plain item there. Artifact id, base and head ride in one HTML comment.
  • Input may be sparse. validate, write and both --file readers accept an object that lists only the must-read files and omits each file’s change type, line counts and diff link. flowctl fills those from the diff, appends the remaining files as a rest-of-diff set, and stores the complete artifact.
  • Mentions are made inert, numbers stay live. @name in authored prose cannot ping anyone. Issue and pull request numbers, URLs and commit SHAs remain links, so fixes #12 still closes that issue on merge.
  • Several specs. specIds lists every spec the body covers, requirement ids are qualified (fn-250:R4), and an uncovered requirement is named with its spec (Uncovered: fn-250:R7).
  • The additions are additive. Five optional authored strings (userImpact, blastRadius, tradeoffs, openItems and shape, which must be one fenced code block) and the optional outcome on a verification cell leave the schema version at 1; stored artifacts stay valid.
  • write never overwrites. It validates and creates one immutable generation under .flow/artifacts/<spec-id>/pr-cognitive-aid/. current answers current, absent, stale, unsupported or invalid, and exposes no artifact unless it is current. A sparse artifact at an unchanged base and head is reused.
  • Errors arrive together. validate and write report every independent violation with its field path in stable order and exit 2. A summary that is only whitespace is rejected by field name.
  • html-input was removed with the HTML render lenses in 7.0. For a visual view of a diff, run /flow-next:visual.

Deterministic “what should run now” for scripted drivers. Attended flow reads it as one hint when it picks the next open spec. flow --auto classifies each hop from the flow skill’s routing reference and the spec’s own status fields instead of this verb. Interactive sessions rarely need it; it is the right probe when scripting a loop or debugging why a driver picked (or skipped) a spec.

Terminal window
flowctl next [--specs-file specs.json] [--require-plan-review] [--require-completion-review] [--json]
{"status": "plan|work|completion_review|none", "spec": "fn-12", "task": "fn-12.3", "reason": "needs_plan_review|needs_tasks|needs_completion_review|resume_in_progress|ready_task|none|blocked_by_spec_deps", "blocked_specs": {"fn-12": ["fn-3"]}}

Selection walks specs in id order and stops at the first actionable unit. A zero-task spec with explicit no_plan: true reports status: work with its spec id and no task id; an explicit --require-plan-review gate still reports needs_plan_review until satisfied. An unmarked zero-task spec reports status: plan with reason: needs_tasks. Direct work creates the single full-spec execution owner; the selector does not mint one. Existing planned tasks retain their normal selection and review gates.

--require-plan-review holds work until the spec’s plan review reaches ship. --require-completion-review gates spec closure. With all tasks done but completion_review_status outside {ship, not_required}, it returns status: completion_review. An unrecognized or absent value satisfies nothing.

These verbs serve /flow-next:flow --auto. They keep their pilot spelling; the /flow-next:pilot command itself was removed in 6.1.0.

Terminal window
flowctl pilot snapshot [--spec <id>] --json # 6.1.0: everything one hop needs, in one read
flowctl pilot strikes record <spec-id> --stage <stage> --reason "<reason>" [--json]
flowctl pilot strikes list [--json] # the two-strike ledger flow --auto writes
flowctl pilot strikes clear <spec-id> [--json] # the human clear after a strike 2/2 verdict
flowctl pilot strikes clear --all [--json]
flowctl pilot-log append --id <id> --action <triaged|advanced|asked|blocked|needs-human> [--stage <stage|->] [--cost-tokens <n>] [--reason "<one line>"] [--json]
flowctl ready --all [--json] # backlog-wide eligibility scan for flow --auto --backlog
flowctl ready --spec fn-1 --admit --in-flight fn-1.1 --cap 3 --json # 6.1.0: rolling admission

pilot snapshot (6.1.0) bundles the run guards, config, candidates with their chain, claim, strike and plan_review_drift facts, the selected spec, the review backend, lifecycle and PR observation, branch existence, QA freshness, and the task list before dispatch. One PR listing joins branches to their open, merged, and closed pull requests. forge names the origin remote’s forge (github, gitlab, bitbucket, or null when none claims the host); on GitLab, merge requests are listed through glab, and on Bitbucket Cloud pull requests through bkt, in the same row shape, and the open one carries the readiness that land’s GitLab gate or Bitbucket gate reads. A failed probe stays explicit, and the caller ends the hop instead of reconstructing the state.

pilot strikes record (6.1.0) increments one cumulative counter per spec under the ledger lock; at count 2 it unreadies the spec. --json returns count and unreadied, and an unknown spec fails.

ready --admit (6.1.0) adds admitted and held lists to the ready read, with mechanical reasons: dependency closure, missing or overlapping Touches (touches-missing when a task has no Touches line), always-serial surfaces, and the --cap capacity. JSON task rows carry parsed touches and transitive dependency facts. The owner can still hold an admitted task for coupling the Touches lines do not show.

pilot strikes reads and clears the ledger at <git-common-dir>/flow-next/pilot-strikes.json, which flow --auto writes when a hop advances nothing. The ledger lives under the git common dir, so worktrees share it and git add -A can never commit it. list is empty-safe (a missing ledger renders empty at exit 0). clear <spec-id> removes exactly one entry atomically; an unknown id is a not-found exit 3 naming the known entries. Clearing never touches spec readiness in either direction. A strike 2/2 verdict unreadies the spec and names this command in its reason string, because on a repo with tracker.readyState armed the board echo re-grants readiness and cannot clear the strike.

pilot-log appends one decision-log row per dispatched stage under .flow/pilot-runs/ when flow --auto --backlog reaches a terminal (auto-gitignored, and not a receipts/ path). --action is the frozen enum above; a live run logs only terminal actions and triaged is diagnostic-only. --cost-tokens is host-reported; flowctl stores the row and never measures cost. --reason "<one line>" stores the host’s verdict reason verbatim as reason on that row, so a chained dispatch’s row begins chained on <parent-id>; ; rows written without the flag keep the frozen {tick, id, action, stage, costTokens} shape.

ready --all is the deterministic substrate for flow --auto --backlog (or pilot.autonomy=backlog). For every open spec it returns ready, noPlan, readySignal, blockedBy (unsatisfied dependency spec ids; a chain parent per spec chain is not listed), and hasSpec, and never a judgment field. Whether an item is workable, thin, or needs a spec is the skill’s agentic read in the triage stage.

Thin plumbing for the project’s standing criteria in the user-owned .flow/criteria.md (G-ID grammar: one line-anchored - **G<N>:** <criterion prose> bullet per criterion). Parse and validate only, since judging compliance belongs to spec completion review (and, on a single-task spec, to that task’s implementation review).

Terminal window
flowctl criteria list [--json] # parse + validate
flowctl criteria prompt-block # print the completion-review injection block
{"success": true, "criteria": [{"id": "G1", "text": "Every route change regenerates the API contract."}], "count": 1, "path": "/abs/path/to/repo/.flow/criteria.md"}

An absent or empty file returns an empty list (and empty prompt-block output) at exit 0 - absence costs nothing anywhere. An existing file that is unreadable or invalid fails closed: nonzero exit with the validation errors on stderr and empty stdout, so a careless append cannot inject error text into a prompt file. Ids must be unique, gaps are allowed, and at most 100 active criteria are accepted. path is absolute, and null when the file is absent.

The host completion-review workflow runs criteria prompt-block before reserving a review round, which turns a broken criteria file into a fast validation error instead of a spent round.

Read-only facts about the committed feature map at .flow/features/, so setup, prime, and flow share one recommendation for /flow-next:features. flowctl never validates the four-section shape (the skill does) and never edits the map.

Terminal window
flowctl features status [--repo <path>]... [--json]
  • recommendation is seed (no map), maintain (the map is due), or none. due is true when a map exists and at least one open drift note or stale feature file exists; reasons[] names each.
  • features[] has one row per feature file (the index README.md excluded): file, state (proven, never-proven, or malformed), last_proven ({date, commit} or null), measured_from (commit, or date when the recorded commit is not in this clone, such as a squashed branch head), commits_since, and stale.
  • commits_since counts default-branch commits (origin/HEAD, then main or master, then HEAD; reported as base) after the proof that change at least one path outside .flow/ that is not documentation. A row is stale when that count reaches features.staleAfterCommits (default 50, reported as threshold), and always when it is never proven or malformed.
  • --repo <path> (repeatable) names a sibling repo that holds product code in a home-base workspace, relative to the repo that holds .flow/. Each proven row then adds that repo’s product commits since the proof date (measured from its own default branch) to commits_since and reports the split as commits_since_by_repo ("." is the .flow/ repo); the output gains repos. A path that is not a git repo root, is the .flow/ repo itself, or has no default branch that resolves exits 2 naming it. Without --repo the output is unchanged.
  • open_drift lists active knowledge entries tagged feature-map-drift as {id, title, path}; it is null when memory is disabled or uninitialised, so only the age condition applies.

Exit 0 (or 2 for a bad --repo). A repository without .flow/ has no map and reads as seed. The command never dispatches /flow-next:features. How the three signals fit together: Keep the feature map current.

The store behind memory and /flow-next:audit: one Markdown file with YAML frontmatter per entry, under .flow/memory/bug/<category>/ or .flow/memory/knowledge/<category>/. Writing entries and the audit plumbing (memory add, audit-scan, apply) are under Rendered artifacts; search reranking is under Judge.

Terminal window
flowctl memory init [--json] # create the category tree; needs memory.enabled
flowctl memory list [--track bug|knowledge] [--category <c>] [--status active|stale|hardened|all] [--json]
flowctl memory search "<query>" [--track ...] [--category ...] [--module <m>] [--tags a,b] [--limit N] [--status ...] [--rerank] [--json]
flowctl memory read <id> [--json]
flowctl memory upsert --track knowledge --category workflow --title "..." --body-file body.md [--json]
flowctl memory mark-stale <id> --reason "<why>" [--audited-by <who>] [--json]
flowctl memory mark-fresh <id> [--audited-by <who>] [--json]
flowctl memory mark-hardened <id> --gate-ref "<path>#<rule-id> -- <note>" [--audited-by <who>] [--json]
flowctl memory list-legacy [--json]
flowctl memory migrate --dry-run [--json]
flowctl memory migrate --yes [--json]
  • Ids. read and the mark-* verbs accept the full id (bug/runtime-errors/<slug>-<date>), slug plus date, or the slug alone (the latest date wins). read also accepts legacy flat-file ids (legacy/pitfalls#N); the mark-* verbs do not.
  • --status defaults to active, so list and search leave out stale and hardened entries. Pass stale, hardened or all to see them.
  • upsert finds an entry by exact title within the track. No match creates one, one match updates it in place, and two or more fail with the ambiguous ids and write nothing. It takes the same fields as memory add.
  • mark-stale sets status: stale and records the reason. mark-hardened demotes an entry to a pointer at the gate that now enforces the lesson; --gate-ref is stored verbatim and the entry’s body stays on disk. mark-fresh returns either kind to active. All three stamp last_audited.
  • list-legacy and migrate read the flat pitfalls.md, conventions.md and decisions.md files from before the categorized layout and propose a track and category per entry from the file name. migrate --dry-run prints the plan; --yes writes it. For classification that reads each entry, run /flow-next:memory-migrate.

Both files live at the repository root, outside .flow/, so they outlive Flow-Next. /flow-next:strategy writes STRATEGY.md; flowctl only reads it.

Terminal window
flowctl glossary add <term> --definition "One line." [--avoid "alt1,alt2"] [--relates-to "x,y"] [--json]
flowctl glossary add <term> --definition-file body.md [--json] # '-' reads stdin
flowctl glossary read <term> [--json]
flowctl glossary remove <term> [--json]
flowctl glossary list [--match "<text>"] [--json]
flowctl strategy status [--json]
flowctl strategy read [--section "key metrics"] [--json]
  • glossary add adds or replaces a term in the nearest GLOSSARY.md above the current directory, creating one at the repository root when none exists. --avoid renders an _Avoid_: line naming terms to replace with this one; --relates-to renders a _Relates to_: line.
  • glossary read walks up from the current directory and returns the first file that defines the term (case-insensitive). remove deletes the term from the file that defines it; removing the last term leaves the file with its # Glossary heading.
  • strategy status reports whether STRATEGY.md exists, whether it is an empty husk, and how many of its sections are filled. strategy read --section prints one section: target problem, our approach, who it’s for, key metrics, tracks, milestones, or not working on.

A green receipt lets work skip re-running a full test gate that already passed on the same code. Work writes and checks them; you can too.

Terminal window
flowctl gate receipt --gate unittest --command "python3 -m unittest discover -q" [--json]
flowctl gate check --gate unittest --command "python3 -m unittest discover -q" [--json]
flowctl gate classify --base <ref> [--json]
  • gate receipt records that the exact command passed at HEAD, in .flow/tmp/green-receipts/<sha8>-<gate>.json. It refuses (exit 1, nothing written) when the worktree has changes outside .flow/ state, because the run tested more than HEAD.
  • gate check exits 0 (skip the re-run) only when a receipt matches the command string’s hash, is under 24 hours old, and was written at HEAD or at an ancestor whose diff to HEAD touches only .flow/ state, with a clean worktree. Any doubt exits 1: run the gate. .flow/config.json and .flow/bin/ count as changes.
  • gate classify reads the changes since <ref> plus the worktree and exits 0 (TIER_B) when every changed path is on the safe list (docs/, agent_docs/, root README*, CHANGELOG.md, GLOSSARY.md and STRATEGY.md, and .flow/ state), so work runs lint and format only. Any code or config extension (.json, .yaml and .toml included), a path under scripts/, or anything the safe list does not name exits 1 (FULL), and so does an empty diff. The path table is fixed and takes no config key; name generated docs your CI checks in your instruction file so the agent runs the full gate for them.

Receipts are local bookkeeping in one checkout. Remote CI never reads them, and a green receipt never means CI can be skipped.

Terminal window
flowctl checkpoint save --spec fn-1 [--json]
flowctl checkpoint restore --spec fn-1 [--json]

save writes the spec, its task files and their runtime claim state to .flow/.checkpoint-<spec-id>.json. restore overwrites the current state with that snapshot. Plan review names restore as its recovery when the conversation is compacted mid-review. Checkpoint files are gitignored; delete stale ones by hand.

flowctl judge classifies one supplied state with a bundled TypeSafe Jev preset and applies that preset’s fixed decision rule, so every host computes the same decision from the same answers. The route preset is the exception: it is code only and never sends a request, with or without a key, so routing never asks Jev. It is the plumbing behind Optional Jev judgments; the skills call it, and you can call it to inspect a decision.

Terminal window
flowctl judge --preset <name> --state-file state.json [--json]
flowctl judge --preset route --spec <spec-id> --json # the live spec's lifecycle, decided in code; sends nothing
flowctl judge --preset tier --task <task-id> --json # 6.1.0: tier inputs from the task; returns tier_line, spawn_model, spawn_effort, implementer
flowctl judge --preset tier --task <task-id> --effort-levels low,medium,high,xhigh,max --default-effort medium --json # worker effort facts from the host
flowctl memory search "windows subprocess" --limit 15 --rerank --json # BM25, then one rerank request over the top 15

Presets: route, fork-gate, memory-rerank, tier. The retired qa-gate preset is an unknown-preset error: the QA gate never asks Jev. The command reads TYPESAFE_API_KEY from the environment at call time; judge.enabled=false disables it. Requests go to jev-latest with a 10-second timeout and two retries only for HTTP 429 and 529 (after 1 s and 2 s); a request estimated over 32k tokens is rejected without sending. The command never writes state, answers, or credentials to disk.

An available result carries success, available, preset, the returned model, typed answers, decision (value, rule, met), latency_ms, and usage. Tier decisions add the three leading candidates as [option, probability] pairs; memory decisions carry every judged entry id and score, reordered, none dropped. --preset route --spec <spec-id> always reports available: false, reason: routing_is_code, and its decision carries value, rule, met, pr_ref, and startable_target_fact for the tail and QA gates to reuse. It takes --spec only: intake routing is the host’s, so a route --state-file is a command error.

The route decision.value is the first match of:

valueWhen
hostThe pull request probe failed, the spec is closed with no observed pull request, spec approval is pending, every remaining task is blocked, or the spec is not ready. rule names which; met is false.
existing_pr_tailA pull request exists for the spec’s branch.
all_done_make_prEvery task is done.
plan_reviewThe plan review reads stale, or (9.17.0+) files the spec cites changed since its SHIP plan review while no task has started; rule is then plan review predates changes to cited files: <paths> (details).
work_plannedThe spec has tasks to work.
work_no_plan_defaultThe spec has no tasks and either records no_plan or is ready with no recorded route. Since 9.8.0 it no longer reads the spec body for plan signals; whether someone asked for a plan is the flow skill’s reading.

--preset tier --task <task-id> returns tier_line, spawn_model, spawn_effort and implementer; an unknown task fails. For a worker the caller passes the host’s effort facts: --effort-levels <lowest,...,highest> (the levels the spawn’s effort parameter accepts, or the bridge’s when the implementer goes over one) and --default-effort <level> (what a spawn without one runs at), plus --explicit-effort for an effort the invocation or routing block names and --role-effort when the worker role pins one. Omit the levels when the spawn takes no effort parameter. spawn_effort is the level for the spawn’s effort parameter, or null for the host default; a bridged implementer carries it as <model> at <effort> in implementer. Scouts pass no effort facts. The rule behind the level is in Worker effort.

The model facts come from the host the same way:

FlagFact
--explicit-model <model>The implementer the invocation named. It outranks the judge’s answer.
--fast-model <model>The host’s configured fast model, used for a task judged mechanical.
--role-model <model>A model the dispatched role pins. It wins over the spawn parameter.
--can-spawn-modelThe host can pick a model when it spawns a worker.
--can-bridgeThe host verified that a bridge to another CLI is reachable.

When the host can reach an explicit model neither by spawn (no spawn-model parameter, or a role pin) nor over a bridge, tier_line reports the session tier and names why.

An unavailable result exits 0 and names the reason so the caller takes its existing fallback. Presets other than route omit the decision:

{"success": true, "available": false, "preset": "fork-gate", "reason": "no_key"}

Reasons: no_key, disabled, http_<status>, transport, timeout, bad_answer, over_budget. A failed PR probe adds pr_probe_failed: true so the caller keeps its failure outcome. Unknown presets, unreadable or non-JSON state files, and missing required state fields exit non-zero; one error names every missing field.

memory search --rerank sends up to 15 BM25 hits in one memory-rerank request and reorders them by Jev score (ties retain BM25 order) without dropping any; --limit applies after the reorder. The judge receives each entry’s id, title, track, category, module, tags and snippet, never its path or BM25 score. JSON adds jev_score and jev_rank to reranked matches and top-level rerank: "jev"; an unavailable judge keeps BM25 order and returns rerank: "bm25", and zero hits send no request.

Since 6.1.0 a skill hands flowctl its judgment and flowctl renders the artifact around it. flowctl derives ids, dates, counts, and commit and branch facts, validates every field, and writes atomically. An invalid payload reports every error together and writes nothing. --skeleton prints the exact authoring shape.

Terminal window
# One-call state reads
flowctl preflight [--spec <id>] --json # planning config plus independent gate probes
flowctl setup-status --json # setup's read-only probes and recorded optional answers
flowctl setup-status --platform opencode --json # claude-code (default), codex, droid, cursor, grok, opencode, muse
# Artifacts rendered from the host's judgment
flowctl prospect write --skeleton
flowctl prospect write --from-json prospect.json --json
flowctl prospect archive <artifact-id> --json # move to .flow/prospects/_archive/
flowctl qa receipt --skeleton
flowctl qa receipt --from-json qa.json [--receipt receipt.json] --json
flowctl memory add --track <track> --category <category> --title "..." --body-file body.md --check-overlap --json
flowctl memory audit-scan --json
flowctl memory apply --plan audit.json --json
# Review plumbing
flowctl review-prompt impl <task-id|branch> --axis correctness --base <ref> --out prompt.md
flowctl review-prompt plan <spec-id> --axis correctness --out prompt.md
flowctl review-prompt completion <spec-id> --axis correctness --base <ref> --out prompt.md
flowctl review-rounds record <spec-id> --kind plan|impl --review-type plan|impl|completion \
--output-file review.md --reservation-id <id> --backend host [--model <model>] --attach [--task <task-id>] [--json]
flowctl review-rounds resume-terminal <spec-id> --review-type completion --json
# Scoped reads
flowctl glossary list [--json] --match "<text>"
  • preflight returns the config snapshot as value plus independent probes for config, strategy, glossary, decision entries, tracker, review backend, and memory. Each probe carries status and value, with an error on failure; each consumer keeps its own fail-open or default behavior.
  • setup-status treats missing or unreadable setup state as a first run. Setup records the optional questions you declined, so a steady re-run asks nothing again. --platform picks which plugin manifest supplies the version and which form of the instruction-file snippet the CLAUDE.md / AGENTS.md check compares against (OpenCode’s flat /flow-next- form, Codex’s AGENTS.md snippet).
  • prospect write takes the title, focus, grounding, ranked survivors, and rejected ideas, and derives the artifact id, date, counts, and rejection rate. prospect archive sets the artifact’s status to archived and moves it to .flow/prospects/_archive/; it refuses when the archive already holds that artifact.
  • qa receipt takes id, qa_outcome, findings, and R-ID coverage, plus optional mode, BLOCKED/NA reasons and per-scenario scenarios rows. It derives commit, branch, timestamps, counts, and prior-finding lineage. Live scenarios are stamped with the current head. A row written as {"id": ..., "run": "carried"} copies its outcome, R-IDs, evidence and head from the prior receipt at the same path; a carry from another spec or branch, or of a scenario that did not pass there, is refused. See QA re-check. BLOCKED or NA never closes a prior finding nobody observed, and an invalid payload leaves the previous receipt in place.
  • memory add --check-overlap returns the overlapping entries without writing, so the host can fold a rediscovery into one with --update <id>.
  • memory audit-scan returns frontmatter, schema errors, recurrence counts, module existence and change evidence, and whether a hardened rule is present. memory apply takes the host’s plan (a list, or {"entries": [...]}); each entry names id and may carry set, stamp, body, move, remove, and replacement. Entries apply atomically one by one, moves and replacements update references, unknown ids are reported while the rest proceed, and a decision record can only be superseded.
  • review-prompt renders the dispatch prompt a host review uses, from the same builders and re-review context as backend review.
  • review-rounds record --output-file requires --backend (host workflows pass --backend host; it no longer defaults to rp) and takes an optional --model naming the reviewer’s model for the attempt row. It derives the verdict, review text, suppressed and classification counts, and unaddressed R-IDs from the review output; structured findings win over prose. A receipt payload that contradicts the output exits 2 before any state changes. --attach publishes the journaled receipt in the same call; the matching reservation is still required. resume-terminal returns {action, status, exit} for completion-review re-entry and rejects unknown persisted states.
  • glossary list --match returns only the entries whose term or avoid-alias occurs in the text (whole word, case-insensitive). The worker’s anchor bundle passes it the task’s title and description.

Review commands also need fewer arguments. Codex plan review runs without --files, an omitted --base resolves to the default branch (origin/HEAD, then main or master), except on completion review, which first uses the base work recorded for the spec and then its chain parent’s branch, and plan and completion receipts default to <repo>/.flow/tmp/. Fan-out saves its round identity before dispatch, so an interrupted round recovers the draws that finished.

A malformed .flow/config.json is reported, never reset. Readers name the file and give line and column for a JSON syntax error, config set refuses to overwrite it, and validate reports a root error. A missing file still means defaults.

Terminal window
flowctl trace <spec-id> [--format md|csv] [--json]

Prints one row per acceptance criterion: the tests that cover it and each test’s result (from a task’s JUnit report when it has one, matched by the R-ID in the test name), its QA evidence, the review findings that name it, and the spec and implementation approvals. A gap check flags every criterion without evidence and every piece of evidence that names no criterion. Exit 0 means no gaps, 1 gaps, 2 an error such as an unknown spec. It reads the committed evidence folder when evidence.persist wrote one and still runs without it; an unreachable forge shows approvals as unknown with a warning. See Flow-Next in regulated environments.

flowctl tracker is the deterministic provider boundary for Linear, GitHub, GitLab, and Jira. Skills supply semantic input files and recovery judgment. The CLI owns credentials, provider requests, pagination, retries, normalization, capability checks, mutations, and transaction boundaries.

Terminal window
flowctl tracker resolve \
[--scope destination|destination.statusIds|destination.stateIds|capabilities] \
[--refresh] [--select KEY=VALUE] [--json]

resolve populates or refreshes tracker.resolved. Scopes that are already fresh are skipped unless you pass --refresh. --select persists an explicit choice when discovery finds multiple candidates. Consuming verbs fail unresolved rather than guessing when required facts are absent.

Wire verbs are locator-addressed and return normalized data:

Terminal window
flowctl tracker wire read --locator "$LOCATOR" [--json]
flowctl tracker wire update --locator "$LOCATOR" [--title TEXT] [--body-file F] [--json]
flowctl tracker wire comment-add --locator "$LOCATOR" --body-file F [--json]
flowctl tracker wire comment-list --locator "$LOCATOR" [--json]
flowctl tracker wire comment-update --locator "$LOCATOR" <comment-id> --body-file F [--json]
flowctl tracker wire comment-delete --locator "$LOCATOR" <comment-id> [--json]
flowctl tracker wire label --locator "$LOCATOR" [--add LABEL]... [--remove LABEL]... [--json]
flowctl tracker wire assign --locator "$LOCATOR" [--add USER]... [--remove USER]... [--json]
flowctl tracker wire list-open [--any-lane] [--unlinked] [--json]
flowctl tracker wire list-states [--json]
flowctl tracker wire unready --locator "$LOCATOR" [--json]
flowctl tracker wire relation-list --locator "$LOCATOR" [--json]
flowctl tracker wire question --locator "$LOCATOR" \
--subject-id ID --blocked-stage STAGE --reason-code CODE \
--question-slug SLUG [--reply-settles] --body-file F [--json]
flowctl tracker wire attach --locator "$LOCATOR" --file PATH [--json]
flowctl tracker wire attach-get <attachment-id> --out PATH [--json]

list-states (4.1.0) enumerates the destination’s workflow states read-only - Linear workflow states or Jira project statuses as {"states": [{"id", "name", "type"}], "complete": bool}. The complete flag distinguishes a provably full listing from a truncated one, so a caller can refuse instead of trusting a partial page; GitHub and GitLab have no workflow-state pool and return a typed capability error. It never writes config - detection stays separate from tracker resolve, which repairs the mapping and writes. relation-list returns normalized directed dependency rows for backlog ordering and fails closed when bounded pagination cannot prove the graph complete. question computes its marker id from the four stable identity inputs, reads comments before writing, and skips an existing id; free prose travels only through the body file and does not affect deduplication. With --reply-settles, a later comment that is not itself a flow-next question settles the open round, so a follow-up on the same topic after a plain reply posts a new round while a rerun of an unanswered round still dedups. Issue starts pass it.

list-open (9.11.0 flags): without a flag it lists the open issues in the exact tracker.readyState, unchanged. --any-lane lists every open issue in the destination on all four trackers, also with tracker.readyState unset; Linear leaves out completed, canceled and duplicate states, and Jira leaves out the Done category. --unlinked drops issues a spec in this checkout already links, from local sync state with no tracker call. Either flag returns compact rows (id, identifier, title, url, labels, and a 500-character excerpt of the body) with issues and truncated kept. Backlog mode reads the ready lane with --unlinked; attended flow’s open-issue triage reads --any-lane --unlinked.

unready (9.11.0) moves an issue out of tracker.readyState: Linear and Jira to the resolved backlog state, GitHub and GitLab by removing the ready label. It reads readiness the same way the projection does and writes only when the issue is ready, so an issue already out of the ready state returns changed: false. It needs no linked spec and writes no .flow/ state. It returns {"issue":{"id","identifier"},"from","to","changed"}. With tracker.readyState unset it returns unresolved/ready_state before any call; with no resolved backlog state (allowed on Jira) unresolved/backlog_slot, and with no Jira transition to it unresolved/transition_unreachable, both without a write. An issue that still reads as ready after the write returns transport/readback.

read on Jira (9.15.0) also takes a locator with only display, an issue key or its /browse/ URL on the configured site (--locator '{"display":"IDEAS-7"}'), and returns the same shape as a read by durable id, with the id filled in. An idea still comes back with its idea block. An unknown key or another site’s URL returns the read’s usual error. Every other verb, and every other tracker, needs both halves of the locator.

With an idea source configured, every wire write verb refuses an idea’s key with capability / idea_read_only before any request; since 9.15.0 that includes unready and question, which read before they write. attach-get turned down by Jira or GitLab carries the tracker’s reason like every other rejection.

Wire verbs are useful for integrations and diagnostics. Lifecycle callers use the facade below because granular verbs do not provide create-if-unlinked, semantic marker deduplication, or aggregate receipts.

Terminal window
flowctl tracker create <spec-id> --title TEXT --body-file F [--event KEY] [--parent ID] [--json]
flowctl tracker create-first --title TEXT --body-file F --retry-key <16-hex> [--parent ID] [--json]
flowctl tracker persist-external <spec-id> --identifier KEY-N \
[--id DURABLE-ID] [--url URL] --source mcp [--event KEY] [--json]
flowctl tracker status <spec-id> \
--to backlog|todo|in_progress|in_review|done|cancelled \
[--reason completed|not_planned|duplicate|reopened] [--event KEY] [--json]
flowctl tracker relate <spec-id> --blocked-by <dependency-spec-id> [--event KEY] [--json]
flowctl tracker sync-body <spec-id> --flow-file F \
[--tracker-body-file F] [--direction push|pull] [--event KEY] [--json]
flowctl tracker sync <spec-id> --op push --event KEY \
[--flow-file F] [--body-file F] [--comment-file F] [--overwrite-diverged]
flowctl tracker sync <spec-id> --op push --status-only --event KEY
flowctl tracker sync <spec-id> --op pull --event KEY \
--flow-file F --body-file F --comments-file comments.json
flowctl tracker sync <spec-id> --op reconcile --event KEY \
--flow-file F --body-file F --source-body-file F \
--comments-file comments.json [--pr-url URL] # --pr-url only with --event makePr
flowctl tracker sync <spec-id> --op pull|reconcile --event KEY --prepare # 6.1.0
flowctl tracker sync <spec-id> --op comment --event KEY \
--body-file F

create uses the spec’s tracker.parent as the parent issue; --parent replaces it and is recorded on the spec with the link. create-first --parent sends the parent and keeps it in the retry record, and a retry whose parent differs from the recorded one refuses with conflict / parent_mismatch. When the final record write fails after the remote create, the pending claim and the failure details carry the parent, so the recovery sync create-first-put keeps it and a retry with the same parent links the existing issue (9.15.0). Pass the same value to spec create --tracker-parent when minting. Both results report parent. On GitLab a numeric epic id counts as set only when the create response carries that epic; otherwise parent is null with degraded kind parent_not_set, a create-first retry reports the same, and no extra request is made. A GitLab parent that is neither ASCII digits nor an epic reference is invalid_input before any request (9.15.0). Jira Cloud, Linear and GitLab (an epic) accept a parent; GitHub and Jira Data Center / Server refuse it with a capability error before any request (Parent issue at creation). Since 9.13.0.

The facade owns create-if-unlinked, lifecycle ordering, marker deduplication, status, readiness and dependency projection, transaction boundaries, and exactly one aggregate receipt. Pull and reconcile receive the already adjudicated final Flow form as an input file; flowctl never authors the semantic merge.

--pr-url is how make-pr links its pull request: every make-pr run with an active bridge calls --op reconcile --event makePr --pr-url <url>, whatever tracker.perEvent.makePr says, and flowctl projects the provider’s native pull request link and records it in the same aggregate receipt. The issue moves to In Review on that call. The flag is refused on every other operation and event.

Since 6.1.0 push renders an omitted body from the spec, and an unchanged spec renders identical bytes; --status-only needs no body. A body-writing push on a linked spec whose tracker body changed since the last sync returns conflict with subtype tracker_diverged and writes nothing. --overwrite-diverged overwrites it and belongs only after a human confirms (Edits made on the tracker). --prepare on pull or reconcile returns the pre-reduction class, the tracker body with dependencies stripped, the base pair, and the genuine comments in one call, excluding marker comments and their hash matches. Its files point to private mode-0600 snapshots that the next facade call consumes; snapshots older than one hour are swept. The agent keeps the conflict and fold decisions.

Jira Cloud only, and only with tracker.perTracker.ideaProjectKeys set (Idea intake). <idea> is a key in a listed project, or its URL on the configured site. Since 9.13.0.

Terminal window
# The idea's text, comments and delivery-linked issues; reads only.
flowctl tracker idea read <idea> [--json]
# Reuse the idea's delivery-linked parent in the delivery project, or create one
# a hierarchy level above tracker.perTracker.issueType (description from F) and
# link it to the idea. --use picks one of several linked parents.
flowctl tracker idea parent <idea> --body-file F [--use KEY] [--json]
# The delivery link from <parent-key> to the idea, when it is not there yet.
flowctl tracker idea link <idea> <parent-key> [--json]
CommandRequests
idea readissue read, comment list
idea parentlink types, issue read, project read; a label search when nothing is linked; create and link only when no parent exists
idea linklink types, issue read; link only when absent

read returns the idea’s text and comments without Jira’s colour markup ({color:#97a0af} tags), since 9.14.0. Since 9.15.0 code and {noformat} blocks come back byte for byte. The ordinary issue read keeps Jira markup.

Each verb reads before it writes, so a repeat creates no second parent and no second link. A parent parent creates carries the label flow-next-idea-<idea>. With no delivery-linked parent, a parent-level issue in the delivery project with that label is reused and linked, so a rerun after a failed link creates nothing (9.15.0). A create screen without a Labels field stops with capability / labels and creates nothing, and a label search response that cannot be read completely stops with transport / malformed_body. parent returns parent (key, created), link (created, existing, or error and retry when the link failed) and notReused (linked issues outside the delivery project or not at the parent level). It stops before any write with conflict / several_parents (several linked parents, or several labelled ones when none is linked; the candidates are in details.candidates), or unresolved / delivery_link_type when the site has zero or several matching link types (details.found).

Other errors: no idea project configured is unresolved; a key outside the listed projects is invalid_input; a key Jira now files outside the discovery projects (an idea moved into delivery) is capability / not_an_idea on all three verbs, before any write (9.15.0); another tracker, or Jira Data Center and Server, is capability. tracker wire read of an idea adds an idea block naming the reference that handles the path, and its request is unchanged; it also reads an idea by its key alone (wire verbs).

Success:

{"success":true,"data":{},"degraded":null,"probe":null}

Failure:

{
"success": false,
"class": "conflict",
"subtype": "several_parents",
"error": "redacted human-readable summary",
"retryable": false,
"details": {"normalized": "todo", "candidates": []}
}

data is verb-specific. degraded records a confirmed capability transition. probe records a capability probe outcome without claiming a transition. Failure details is typed: rate limits include retry_after_s, capability failures include capability and required_plan, conflicts include normalized and candidates, and MCP continuations include action and payload. Branch on class and subtype, never provider error text.

subtype (9.15.0) is present whenever the error has one and names the case within the class that the verb docs branch on (several_parents, delivery_link_type, parent_mismatch, idea_read_only, …). The field is additive, so a caller that ignores it keeps working. error is redacted. On GitLab the redaction also covers GITLAB_ACCESS_TOKEN, OAUTH_TOKEN, glab’s config under GLAB_CONFIG_DIR, and every configured host’s stored token when the host glab used is not known (9.15.0).

ExitclassMeaning
0successCompleted; inspect degraded and probe
2invalid_inputCLI input or local contract is invalid
3inactiveTracker bridge is inactive
4unresolvedRequired tracker.resolved facts are absent or incomplete
5authCredential is absent or rejected
6rate_limitedProvider rate limit; retry only when retryable is true
7transportProvider request failed or returned an unusable response
8not_foundAddressed provider object does not exist
9capabilityRequested operation is unsupported by the resolved capability set
10conflictDurable identity, status mapping, or transaction state conflicts
11stale_idPersisted provider identity is stale
12external_action_requiredHost must perform the described MCP continuation

flowctl sync holds the bridge’s local state: which issue each spec links, the paired merge base, receipts, and deferred conflicts. It never calls a provider; flowctl tracker does. It is unrelated to /flow-next:sync, which is plan-sync.

Terminal window
# Bridge and link state
flowctl sync active [--json] # bridge on? (tracker.enabled, or tracker.type set)
flowctl sync get-state <spec-id> [--json]
flowctl sync set-tracker-id <spec-id> <tracker-id> [--identifier WOR-17] [--url URL] [--force] [--json]
flowctl sync set-last-synced <spec-id> [--at ISO] [--json] # defaults to now
flowctl sync set-merge-base <spec-id> --flow-file F --tracker-file F [--json] # or --flow / --tracker text
flowctl sync clear <spec-id> [--json] # unlink: wipe the spec's tracker state
# Listings and guards
flowctl sync list-unsynced [--json] # specs with no linked issue
flowctl sync list-stale [--older-than-hours N] [--json] # default N: tracker.staleAfterHours
flowctl sync check-collisions [--json] # one issue linked by two specs
# Dependency ledger
flowctl sync list-dep-relations <spec-id> [--json]
flowctl sync set-dep-relation <spec-id> --dep-spec <id> \
--from-tracker-id <blocked-issue> --to-tracker-id <blocking-issue> [--type blocks] [--source flow] [--json]
# Create-first recovery records
flowctl sync create-first-key --type github --title "Fix login" [--body-file b.md] [--parent <id>] [--json]
flowctl sync create-first-get --key <key> [--json] # exit 1 when absent
flowctl sync create-first-put --key <key> --id ... --identifier ... --url ... --title ... --transport ... \
[--spec-id <id>] [--if-absent | --expect-spec-id <id>] [--json]
flowctl sync create-first-clear --key <key> [--json]
# Receipts, audit, deferral
flowctl sync receipt <spec-id> --status pushed|pulled|merged|updated|diverged|queued|errored|noop \
[--event KEY] [--tracker-id ID] [--transport T] [--merges-file F] [--note N] [--json]
flowctl sync check <spec-id> --events capture,makePr --since <iso> [--json]
flowctl sync defer <spec-id> --summary "..." [--suggested "..."] [--reason "..."] [--branch B] [--json]
  • set-tracker-id stores the durable issue id (the dedupe key), the display identifier and the URL. It refuses an id another spec already links unless you pass --force. With tracker.perTracker.ideaProjectKeys set, it refuses an idea’s key in any letter case, and given only a durable id it asks for --identifier, so a spec is never linked to an idea as its own issue (9.15.0). clear wipes the spec’s tracker state, its recorded parent included, and changes nothing in the tracker.
  • set-merge-base takes both halves together, the Flow form and the tracker form, so the three-way merge base never mixes two sync points. A one-sided write is refused.
  • list-dep-relations reads the spec’s depends_on_epics and, for each dependency, its linked issue, its local status, and whether the edge is already recorded. set-dep-relation records a projected blocked-by edge in the spec’s depRelations ledger. --from-tracker-id is the blocked issue, --to-tracker-id the blocking one. Re-recording an edge changes nothing. Creating the relation on the tracker is flowctl tracker relate.
  • The create-first-* verbs keep the recovery record for an issue created before any local spec exists, at .flow/create-first/<key>.json (gitignored). The key is the first 16 hex characters of a hash of tracker type, title and body, so a retried run finds the issue it already created and links it instead of creating a second. --parent (9.13.0) adds the parent to the hash, so the same work under another parent gets its own key; without it the key is unchanged. put --if-absent records the minted spec id only while none is recorded; the loser of a race exits 10 with subtype spec_already_minted naming the winner. --expect-spec-id updates a claim you already own. A later put keeps the parent the record already holds and, for the same issue, a recorded degraded (a GitLab parent_not_set), so a retry compares and reports them as the first create did (9.15.0).
  • check is the read-only audit the lifecycle skills run at the end: for each event that fired, OK:<event> or MISSING:<event> when its perEvent leaf is on, the bridge is active, and no receipt with that event tag exists since --since. With the bridge off it exits at once. It always exits 0.
  • defer queues a conflict to the deferred-findings file (.flow/review-deferred/<branch>.md) instead of asking, which is what an unattended run does.

Tracker operations explains when the skills call each of these.

.flow/
├── meta.json
├── config.json
├── specs/
├── charts/ # optional chart discovery maps + decision records
├── tasks/
├── memory/
├── features/ # optional user-POV feature map
├── prospects/ # optional ranked idea lists
├── templates/ # optional spec template (spec.md)
├── criteria.md # optional standing criteria
├── artifacts/ # PR briefing source generations
├── review-receipts/ # review receipt copies
├── pilot-runs/ # gitignored backlog-mode decision log
├── bin/
└── usage.md

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

ResponsibilityWhy it lives in flowctl
ID allocationMust be deterministic and merge-safe
State transitionsMust be machine-readable
ValidationMust run in CI and local shells
ReceiptsMust survive chat context
MigrationMust 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-facing commands follow the sequence at the top of this page, with --json on the reads. Direct CLI usage is for automation and debugging; the docs teach the slash-command workflow first because that is the product surface.