CLI overview
Castellan is a single binary (castellan) 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.
CASTELLAN_MUX_AUTO,CASTELLAN_SESSION_SPEND_CAP_USD - Layered config files — see
castellan.toml
Output modes
| Mode | Flag / entrypoint | Consumer | Reference |
|---|---|---|---|
| Human text | default | Interactive terminal | run |
| NDJSON events | castellan run --json | CI, automation, log pipelines | run |
| MCP stdio | castellan mcp | Cursor, Claude Desktop, other MCP clients | mcp, MCP tools |
| ACP stdio | castellan acp | Editor-class agents (Zed, experimental) | ACP integration |
| Socket NDJSON | castellan multiplexer server | Dashboard, remote attach, HerdR parity | Socket API |
One runnable recipe per mode:
# text — human terminal
castellan run --goal "reach target" --plugin gridworld
# json — typed NDJSON events for CI (episode JSON also lands in .castellan/episodes/)
castellan run --goal "reach target" --plugin gridworld --json | grep episode_end
# mcp — stdio JSON-RPC (tools/list handshake)
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}\n' | castellan mcp
# socket — multiplexer NDJSON API
castellan multiplexer server &
castellan multiplexer status
# acp — agent client protocol over stdio
castellan acp doctor
Episode JSON is always written to .castellan/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, episodes, recipes, drift-check, memory, integration, vitals, genome, dashboard, completions, ipc (deprecated). Run castellan <cmd> --help for flags. Recipes are defined in castellan.toml [[recipes]].
Shell completions
Completions are generated from live clap metadata so they stay in sync with the CLI:
castellan completions bash # bash completion script
castellan completions zsh # zsh completion script
castellan completions fish # fish completion script
Install examples:
# bash (user-local)
mkdir -p ~/.local/share/bash-completion/completions
castellan completions bash > ~/.local/share/bash-completion/completions/castellan
# zsh
castellan completions zsh > "${fpath[1]}/_castellan"
# fish
mkdir -p ~/.config/fish/completions
castellan completions fish > ~/.config/fish/completions/castellan.fish
Re-run after upgrading castellan when subcommands or flags change.
Help snapshots
CLI help is snapshot-tested in CI. After intentional CLI changes:
UPDATE_SNAPSHOTS=1 cargo test -p castellan-cli cli_help_snapshot
See Deployment.