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, completions, ipc (deprecated). Run flock <cmd> --help for flags.

Shell completions

Completions are generated from live clap metadata so they stay in sync with the CLI:

flock completions bash   # bash completion script
flock completions zsh    # zsh completion script
flock completions fish   # fish completion script

Install examples:

# bash (user-local)
mkdir -p ~/.local/share/bash-completion/completions
flock completions bash > ~/.local/share/bash-completion/completions/flock

# zsh
flock completions zsh > "${fpath[1]}/_flock"

# fish
mkdir -p ~/.config/fish/completions
flock completions fish > ~/.config/fish/completions/flock.fish

Re-run after upgrading flock when subcommands or flags change.

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

Keyboard shortcuts