CLI Reference¶

Complete reference for the Brat command-line interface.

Global Flags¶

Available on all commands:

Initialization¶

brat init¶

Initialize Brat harness in the current repository.

brat init [OPTIONS]

Behavior:

• Initializes Grite ledger (grite init)
• Creates .brat/config.toml (unless --no-config)
• Starts daemon (unless --no-daemon)

Status¶

brat status¶

View convoys, tasks, and sessions.

brat status [OPTIONS]

Convoy Commands¶

brat convoy create¶

Create a new convoy.

brat convoy create --title <TITLE> --goal <GOAL>

brat convoy list¶

List all convoys.

brat convoy list [OPTIONS]

brat convoy show¶

Show convoy details.

brat convoy show <CONVOY_ID> [OPTIONS]

brat convoy add-repo¶

Add a repository to a convoy.

brat convoy add-repo <CONVOY_ID> --repo <PATH>

Task Commands¶

brat task add¶

Add a task.

brat task add [OPTIONS]

brat task list¶

List tasks.

brat task list [OPTIONS]

brat task show¶

Show task details.

brat task show <TASK_ID> [OPTIONS]

brat task assign¶

Assign a task to an actor.

brat task assign <TASK_ID> --assignee <ACTOR_ID>

brat task comment¶

Add a comment to a task.

brat task comment <TASK_ID> --body <TEXT>

brat task close¶

Close a task.

brat task close <TASK_ID> --reason <done|dropped>

Mayor Commands¶

brat mayor start¶

Start the Mayor session.

brat mayor start

brat mayor ask¶

Send a prompt to the Mayor.

brat mayor ask "<PROMPT>"

brat mayor status¶

Check Mayor session status.

brat mayor status

brat mayor stop¶

Stop the Mayor session.

brat mayor stop

Session Commands¶

brat session list¶

List active sessions.

brat session list [OPTIONS]

brat session tail¶

View session output.

brat session tail <SESSION_ID> [OPTIONS]

brat session stop¶

Stop a session.

brat session stop <SESSION_ID>

Role Commands¶

brat witness run¶

Run the Witness to spawn agents.

brat witness run [OPTIONS]

brat refinery run¶

Run the Refinery to process merge queue.

brat refinery run [OPTIONS]

brat deacon run¶

Run the Deacon for cleanup.

brat deacon run [OPTIONS]

Swarm Commands¶

brat swarm start¶

Start multiple agents for a convoy.

brat swarm start --n <COUNT> --convoy <ID>

brat swarm stop¶

Stop agents for a convoy.

brat swarm stop --convoy <ID>

Lock Commands¶

brat lock status¶

View lock status.

brat lock status [OPTIONS]

brat lock acquire¶

Acquire a lock.

brat lock acquire --resource <R> --ttl <DURATION>

brat lock renew¶

Renew a lock.

brat lock renew --resource <R> --ttl <DURATION>

brat lock release¶

Release a lock.

brat lock release --resource <R>

Daemon Commands¶

brat daemon start¶

Start the daemon.

brat daemon start [OPTIONS]

brat daemon stop¶

Stop the daemon.

brat daemon stop

brat daemon status¶

Check daemon status.

brat daemon status [OPTIONS]

brat daemon restart¶

Restart the daemon.

brat daemon restart [OPTIONS]

brat daemon logs¶

View daemon logs.

brat daemon logs [OPTIONS]

Utility Commands¶

brat doctor¶

Health check and repair.

brat doctor [OPTIONS]

brat sync¶

Sync with remote.

brat sync [OPTIONS]

brat export¶

Export data.

brat export --format <md|json>

brat config validate¶

Validate configuration.

brat config validate

brat feed¶

View event feed.

brat feed [OPTIONS]

Examples¶

Full Workflow¶

# Initialize
brat init

# Create convoy
brat convoy create --title "Bug fixes" --goal "Fix P0 bugs"

# Add tasks
brat task add --convoy <id> --title "Fix crash" --paths src/app.rs

# Run agents
brat witness run --once

# Monitor
brat status --watch

# Merge
brat refinery run --once

Using the Mayor¶

# Start Mayor
brat mayor start

# Analyze and create work
brat mayor ask "Analyze src/ and create tasks for bugs"

# View results
brat status

# Run agents
brat witness run --once

CI/CD Integration¶

# Run without daemon
brat --no-daemon witness run --once
brat --no-daemon refinery run --once

# Check status
brat --no-daemon status --json