swarm CLI reference

swarm is the control-plane CLI shipped by @dogfood-lab/dogfood-swarm. The full source of truth is packages/dogfood-swarm/cli.js; this page is a per-verb quick-reference so you can scan all 21 verbs without swarm --help-ing your way through them.

For verbs that already have a dedicated handbook page, this page lists the synopsis and a one-line summary, then links out. Those deep-dive pages are:

swarm revalidate, swarm rewind, swarm redrive — the Three R’s recovery contract
swarm history — deep-audit verb for wave_state_events

The verbs below are the rest of the CLI surface — the ones you reach for during normal day-to-day swarm operation.

swarm init

Bootstrap a new run against a repo. Walks the file tree, detects domain candidates from swarms/domain-map-suggestions.json (or equivalent), creates an entry in the runs table, and writes a save-point tag (swarm-save-<run-id>) at the current HEAD so swarm rewind has a safe target later.

Usage: swarm init <repo-path> [--repo org/name]

Example:
  $ swarm init E:/AI/my-repo
  $ swarm init E:/AI/my-repo --repo dogfood-lab/my-repo

The output lists the draft domain map. Review it, then run swarm domains <run-id> --freeze (or pass --auto-freeze on the first dispatch).

swarm domains

Inspect, edit, freeze, or unfreeze the per-run domain map. The domain map is what determines per-agent file ownership; freezing it locks the surface so dispatch can produce verifiable per-agent prompts. Subcommands (all via flags) cover the full lifecycle: --freeze, --unfreeze --reason "...", --edit <name>, --add <name> --globs '[...]', --remove <name>, --history.

Usage:
  swarm domains <run-id>             # show current map
  swarm domains <run-id> --freeze    # lock for the run
  swarm domains <run-id> --unfreeze --reason "."
                                     # unlock (reason required)
  swarm domains <run-id> --history   # change events

Every mutation lands in domain_events with the operator-supplied reason — same audit discipline as the wave/agent state events.

swarm dispatch

Create a new wave for a phase and write per-agent prompts to swarms/<run-id>/wave-<N>/. The phase names the work shape — health-audit-a, health-amend-b, stage-d-amend, feature-execute, and friends. Pass --skip-verify on amend phases to enable the parallel-wave verification discipline (agents skip per-agent npm test; coordinator runs one serial verify after swarm collect).

Usage: swarm dispatch <run-id> <phase>
                      [--auto-freeze]
                      [--isolate]
                      [--skip-verify]

Example:
  $ swarm dispatch <run-id> health-audit-a
  $ swarm dispatch <run-id> health-amend-b --skip-verify

Phases: health-audit-a/b/c, health-amend-a/b/c, stage-d-audit, stage-d-amend, feature-audit, feature-execute.

swarm collect

Validate every agent’s output JSON against the canonical Ajv envelope and the phase-specific legacy validator, enforce file-ownership per the frozen domain map, and merge findings into the control plane. This is the gate that flips a wave from dispatched to collected (or to failed when any agent’s output is BLOCKED).

Usage: swarm collect <run-id>
                     --domain=name:path
                     [--domain=name:path ...]

Example:
  $ swarm collect <run-id> \
      --domain=backend:outputs/backend.json \
      --domain=tests:outputs/tests.json

When --skip-verify was used on dispatch, the output ends with a [!] SERIAL VERIFY REQUIRED [!] banner; run npm run verify against the cumulative tree before swarm status to advance the wave.

swarm verify

Run build verification on the run’s repo. Auto-detects the toolchain (node / python / rust) by probing for package.json, pyproject.toml, Cargo.toml, etc., or accepts an explicit --adapter. Use --probe-only to see which adapters would match without running anything.

Usage: swarm verify <run-id>
                    [--adapter node|python|rust]
                    [--probe-only]

Example:
  $ swarm verify <run-id>                    # auto-detect
  $ swarm verify <run-id> --adapter python   # force python
  $ swarm verify <run-id> --probe-only       # dry probe

swarm verify-fixed

Re-audit findings that an amend agent marked [fixed]. Classifies each into verified, regressed, claimed-but-still-present, or unverifiable, and writes a delta JSON to swarms/<run-id>/verify-fixed-<wave>.json. Used as a CI gate: exits non-zero when regressed + claimed-but-still-present > --threshold (default 0).

Usage: swarm verify-fixed <run-id>
                          [--threshold=N]
                          [--format=text|markdown|json]
                          [--legacy-v1]

Example:
  $ swarm verify-fixed <run-id> --threshold=0
  $ swarm verify-fixed <run-id> --format=markdown > delta.md

Schema v2 is default (vantage-point disclosure via verified_via); pass --legacy-v1 for backward-compat consumers.

swarm verify-recurring

Audit findings that have multiple [fixed] events in their history — the regression-and-reclaim pattern. Writes a delta JSON to swarms/<run-id>/verify-recurring-<wave>.json so you can see at a glance which findings keep coming back. Output schema verify-recurring-delta/v1.

Usage: swarm verify-recurring <run-id>
                              [--threshold=N]
                              [--format=text|markdown|json]

Example:
  $ swarm verify-recurring <run-id>

swarm verify-unverified

Re-classify findings that were deferred as unverified against the current code state. The wave classifier marks findings unverified when no scope is supplied for re-checking; this verb resolves them. Writes delta JSON to swarms/<run-id>/verify-unverified-<wave>.json. Output schema verify-unverified-delta/v1.

Usage: swarm verify-unverified <run-id>
                               [--threshold=N]
                               [--format=text|markdown|json]

Example:
  $ swarm verify-unverified <run-id>

swarm verify-approved

Pre-amend gate that confirms approved findings still have valid anchors in the current code state. Exit code 2 (broken anchor) blocks subsequent amend dispatch — wired into CI as a check so amend agents never run against a finding whose anchor has drifted. Writes delta JSON to swarms/<run-id>/verify-approved-<wave>.json.

Usage: swarm verify-approved <run-id>
                             [--threshold=N]
                             [--format=text|markdown|json]

Example:
  $ swarm verify-approved <run-id>  # gate before amend

swarm receipt

Export a durable wave receipt — JSON + Markdown — to swarms/<run-id>/wave-<N>/ and store the paths in the control plane. The receipt is the auditable, portable record of the wave’s outcome (counts, agents, findings, recommendation). Defaults to the latest wave; pass a wave number to export an older one.

Usage: swarm receipt <run-id> [wave-number]

Example:
  $ swarm receipt r-2026-05-20-001        # latest wave
  $ swarm receipt r-2026-05-20-001 3      # wave 3

swarm advance

Check the phase-advancement gates and (if they pass) promote the run to the next phase. Use --check-only to see gate results without mutating, --history to read the promotion log, or --override --reason "..." to force-promote past a soft block. Hard blocks (e.g. blocked agent_runs) cannot be overridden — fix the underlying state first.

Usage: swarm advance <run-id>
                     [--check-only]
                     [--history]
                     [--override --reason "..."]

Example:
  $ swarm advance <run-id> --check-only
  $ swarm advance <run-id>
  $ swarm advance <run-id> \
      --override --reason "operator accepts soft warn"

swarm status

Render the full control-plane status for a run — phase, waves, agent states, findings counts, recovery breadcrumbs. The scan-first surface: read this when you want to know “what is this run, where is it in the lifecycle, what’s blocking it, and what do I run next.” The trailing Next: line is the canonical pointer to the next action.

Usage: swarm status <run-id>

Example:
  $ swarm status r-2026-05-20-001

When a wave has interesting history (override transitions, multiple state changes), a breadcrumb points at swarm history <wave-id> — see swarm history.

swarm resume

Redispatch incomplete agents in the latest wave. Useful when an agent crashed or was cancelled mid-run and its output never arrived. Re-creates the prompt and re-issues the dispatch; the agent_run row’s state machine ensures completed agents in the same wave aren’t redispatched (their work is preserved).

Usage: swarm resume <run-id>

Example:
  $ swarm resume r-2026-05-20-001

For resuming a failed wave (not just incomplete agents), see swarm redrive — same wave_id, completed work preserved.

swarm approve

Mark findings as approved-for-amend. Either --all to approve every new or recurring finding on the run, or --ids F-001,F-002,... to approve a specific subset. Findings must be approved before the amend phase can pick them up; the approved status is recorded in finding_events with a bulk-approve event marker.

Usage: swarm approve <run-id>
                     [--all | --ids F-001,F-002]

Example:
  $ swarm approve <run-id> --all
  $ swarm approve <run-id> --ids F-091578-034,F-091578-042

swarm persist

Export the canonical truth from the swarm control plane to downstream systems — typically the testing-os ingest pipeline for cross-repo intelligence. Use --dry-run to preview the export without writing, --ingest to invoke the downstream ingester after the export lands.

Usage: swarm persist <run-id> [--ingest] [--dry-run]

Example:
  $ swarm persist r-2026-05-20-001 --dry-run
  $ swarm persist r-2026-05-20-001 --ingest

swarm findings

Print a findings digest for a wave (default: the latest). Format auto-detects — text on a TTY, markdown when piped or redirected — so the same command works for human scanning and for CI gates. Override with --format=text|markdown|json or the DOGFOOD_FINDINGS_FORMAT env var (raw|human|json).

Usage: swarm findings <run-id> [wave-number]
                      [--format=text|markdown|json]

Example:
  $ swarm findings <run-id>            # latest wave, auto fmt
  $ swarm findings <run-id> 3 --format=json   # wave 3 JSON
  $ swarm findings <run-id> > digest.md       # md to file

Exit codes are 3-way: 0 clean, 1 findings present, 2 audit pipeline broken — so CI can distinguish “no findings” from “pipeline broke.”

swarm runs

List every run in the control-plane DB, with wave + findings counts and the created-at timestamp. The orientation verb: run this first when you’ve forgotten what runs exist or which run id is the latest one.

Usage: swarm runs

Example:
  $ swarm runs