CLI reference

Generated from flock --help (snapshot-tested in crates/flock-cli/tests/cli_help_snapshot.rs).

Top-level commands

Command	Purpose
`run`	Scheduler-led goal loop with plugin verifier
`evolve`	Topology evolution from episode logs
`remote`	Multiplexer attach + governed goal run
`multiplexer`	PTY server (`server`, `ensure`)
`herd`	HerdR-shaped UX (`server`, `status`, `tabs`, `attach`, `wait`, …)
`replay`	Replay episode JSON; `--continue-run` resumes checkpoint
`swarm-demo`	Multi-pane scheduler-led demo
`ipc`	Legacy JSON-line bridge (deprecated)
`acp`	Agent Client Protocol stdio server
`rah-demo`	Depth-3 RAH pane spawn demo
`skills`	List SKILL.md bundles
`drift-check`	Verification manifest guardrails
`plugin`	`list`, `info`, `new`, `install`
`mcp`	MCP stdio JSON-RPC server
`telemetry`	Query `~/.config/flock/telemetry.db` (sessions, transitions, vitals)
`doctor`	Staged runtime diagnostics (`--json` for automation)
`vitals`	Circulation vitals from latest episode
`genome`	`list`, `lineage` from topology archive
`dashboard`	Ratatui control tower; `--history` for telemetry JSON

`flock run`

flock run --goal <GOAL> [--plugin gridworld] [--rlm] [--max-steps 8]
          [--audit <PATH>] [--json] [--mcp] [--model <URL_OR_NAME>]
          [--genome <ID>] [--seed-archive] [--archive .flock/topology_archive.json]
          [--write-back] [--no-write-back]

--genome or --seed-archive seeds topology/coordination from the evolve archive before the run. Episode logs include a genome_seed event.

After a successful run, --write-back merges episode fitness into the archive (automatic when --seed-archive is used unless --no-write-back is set).

--model mock uses the deterministic stub. HTTP URLs and named providers require building with --features llm-http. The model is used only on the plugin verify path or RLM loop — never in PressureScheduler wake decisions.

`flock remote`

flock remote --goal <GOAL> [--plugin gridworld] [--socket <PATH>]
             [--ssh user@host] [--stub] [--audit <PATH>]

Governance pipeline (with_governance) applies on the remote hot path. Audit JSONL optional via --audit.

`flock telemetry`

flock telemetry [--limit 20] [--db <PATH>]
flock dashboard --history [--limit 20]

Headless query of dashboard telemetry (sessions, agent transitions, vitals snapshots). No TTY required.

`flock doctor`

flock doctor [--workspace .] [--json]

Staged pass/fail checks: multiplexer socket, governance manifest, plugin registry, evolve archive, latest episode vitals. Exits non-zero when any stage fails.

`flock evolve`

flock evolve [--episodes 10] [--workspace .flock/episodes] [--hook rust|seed-only] [--summarize]

--summarize compacts the episode corpus to .flock/episode_summary.json without running evolution. The proposer reads this summary when present (DRY with substrate heatmap).

`flock mcp`

flock mcp

Stdio JSON-RPC: initialize, tools/list, tools/call. See MCP tools.

`flock plugin install`

flock plugin install --from <DIR>
flock plugin install --git <URL> [--name <NAME>]

Installed plugins register automatically via plugins.toml and build.rs — no registry.rs edit.

Help snapshots

UPDATE_SNAPSHOTS=1 cargo test -p flock-cli --test cli_help_snapshot

Keyboard shortcuts

Flock