The Brat CLI is the harness control plane. It orchestrates roles and uses Grite for all task/memory state.
- Non-interactive by default
- Structured output via
--json - Safe by default; destructive actions require explicit flags
- Streaming and waiting require explicit flags (
--follow,--wait --timeout) - Single CLI:
bratwraps Grite;griteis for debugging only - Daemon auto-starts on commands that benefit from it (disable with
--no-daemon)
--json- Output in JSON format--quiet- Suppress human-readable output--repo <path>- Target a specific repository--no-daemon- Don't auto-start the daemon (run in standalone mode)
- Commands operate on the current repo by default.
- Use
--repo <path>to target a different repo. - Use
--all-reposon list/status commands to aggregate across repos. - All CLI commands connect to the single
bratdsession registry when it is running.
brat init [--no-daemon] [--no-tmux] [--no-config]brat status [--json] [--all-repos] [--convoy <convoy_id>] [--watch]brat convoy create --title ... --goal ...brat convoy create --mirror --repos <paths>brat convoy list [--json] [--all-repos]brat convoy show <convoy_id> [--json]brat convoy add-repo <convoy_id> --repo <path>brat task add --convoy <id> --title ... --paths ...brat task add --solo --title ... --paths ...brat task add --convoy <id> --repo <path> --title ...brat task assign <task_id> --assignee <actor_id>brat task list [--json] [--all-repos] [--label <label>]brat task show <task_id> [--json]brat task comment <task_id> --body ...brat task close <task_id> --reason donebrat swarm start --n <count> --convoy <id>brat swarm stop --convoy <id>brat session list [--json]brat session tail <session_id> --lines 200 [--json]brat session stop <session_id>brat witness run --oncebrat refinery run --oncebrat deacon run --oncebrat feed --once|--follow [--timeout <ms>]brat lock status [--json]brat lock acquire --resource <R> --ttl 15mbrat lock renew --resource <R> --ttl 15mbrat lock release --resource <R>brat doctor --check|--rebuild(see note below)brat sync --pull|--pushbrat export --format md|jsonbrat config validatebrat daemon start [--port <port>] [--idle-timeout <secs>] [--foreground]brat daemon stopbrat daemon status [--json]brat daemon restart [--port <port>] [--idle-timeout <secs>]brat daemon logs [-n <lines>]brat api [--host <host>] [--port <port>] [--idle-timeout <secs>](deprecated, usebrat daemon start --foreground)
brat doctor --check: read-only harness health validationbrat doctor --rebuild: rebuilds harness state (callsgrite rebuildinternally)
For substrate-level health checks, use grite doctor --fix directly.
--jsonis supported on all read commands- Errors return structured details
brat status --jsonincludes aninterventionsarray with recommended remediation commands (seedocs/usability.md).brat status --json --all-reposreturns areposarray (seedocs/brat-status-schema.md).
Brat reads and writes Grite issues, comments, labels, and locks. It never writes tracked files for metadata.
brat init behavior:
- Initializes the Grite ledger (equivalent to
grite init) - Creates
.brat/config.tomlif missing (unless--no-config) - Starts
bratdunless--no-daemon - Optionally creates the tmux control room (unless
--no-tmux)