CLI overview

Flock is a single binary (flock) with subcommands for goal runs, evolution, multiplexer control, MCP, and diagnostics.

Precedence

Configuration resolves in this order (highest wins):

CLI flags — e.g. --goal, --plugin, --json
Environment variables — e.g. FLOCK_MUX_AUTO, FLOCK_SESSION_SPEND_CAP_USD
Layered config files — see flock.toml

Output modes

Mode	Flag / entrypoint	Use when
Human text	default	Interactive terminal
NDJSON events	`flock run --json`	CI, automation, log pipelines
MCP stdio	`flock mcp`	Cursor, Claude Desktop, other MCP clients
ACP stdio	`flock acp`	Editor-class agents (Zed, experimental)
Socket NDJSON	`flock multiplexer server`	Dashboard, remote attach, HerdR parity

Episode JSON is always written to .flock/episodes/<goal-id>.json on successful runs (separate from --json stdout).

Top-level commands

Command	Page
`run`	run
`evolve`	evolve
`remote`	remote
`herd`	herd
`plugin`	plugin
`mcp`	mcp
`telemetry`	telemetry
`doctor`	doctor
`replay`	replay
`swarm-demo`, `rah-demo`	demos

Other commands: multiplexer, acp, skills, drift-check, memory, integration, vitals, genome, dashboard, ipc (deprecated). Run flock <cmd> --help for flags.

Help snapshots

CLI help is snapshot-tested in CI. After intentional CLI changes:

UPDATE_SNAPSHOTS=1 cargo test -p flock-cli cli_help_snapshot

See Deployment.

Recipes

First episode (gridworld):

flock run --goal "reach target" --plugin gridworld

Headless CI with typed events:

flock run --goal "reach target" --plugin gridworld --json | grep episode_end

Daily-driver mux path:

flock multiplexer server &
flock dashboard &
flock run --goal "reach target" --plugin gridworld --mux

Evolve then seed a run:

flock evolve --episodes 10 --workspace .flock/episodes
flock run --goal "reach target" --plugin gridworld --seed-archive