The brains-ai command line

Install, wire and run

setup registers a Workspace. serve-all runs the supervised local stack; serve and mcp expose individual servers. wire and unwire manage supported harness configuration. The service command group manages the optional background stack.

brains-ai --help
brains-ai setup --help
brains-ai wire --help
brains-ai service install --help

Use Quickstart for an installation sequence, not a bare command list. upgrade updates an editable Git checkout; it is not the package-manager upgrade command for a pipx installation.

Sessions, tasks and claims

Session commands include session-start, session-heartbeat and session-end. Use state to orient and the handoff-set, handoff-pick, handoff-list and handoff-clear commands for continuity. Checkpoints are available through MCP; do not infer a CLI command from the noun.

Task operations are flat commands: task-create, task-list, task-claim, task-complete, task-release and task-handoff. Workspace ownership uses workspace-claim, workspace-release and workspace-claims.

brains-ai task-claim --code <task-code> --session <session-id>
brains-ai workspace-claim --session <session-id> --minutes 30
brains-ai task-handoff --from-code <task-code> --title "<follow-up>" --session <session-id>

Replace placeholders with actual IDs and titles. task-handoff completes the predecessor and creates a dependent follow-up atomically. See Coordination for the workflow.

Peer help, mail and knowledge

help-file opens a request. help-get inspects it; help-claim-code accepts exactly that code. help-claim instead waits for eligible queued work. help-answer requires evidence; release, cancel, wait and list have corresponding help-* commands.

brains-ai help-claim-code <help-code> --session <peer-id>
brains-ai mailbox inbox --help
brains-ai search-repo "migration contract" --path .

mailbox is a real command group. inbox-wait waits for peer help, not mail. Use the MCP knowledge tools to add, search and resolve findings; repository lookup is bounded text search, not semantic retrieval.

Decisions and evidence

Use decision-file, decision-list, decision-route, decision-escalate and decision-resolve for human questions. audit-list and audit-verify inspect the chain; governed-list and governed-sweep inspect and settle governed records. Read the trust boundary before interpreting these as enforcement.

Inspect and recover local state

db, queue-health and credentials are command groups. readiness, backup, backup-inspect, restore, recovery-policy and recovery-drill are top-level commands.

brains-ai backup ./brains-backup.tar.gz
brains-ai backup-inspect ./brains-backup.tar.gz
brains-ai db verify-backup --help
brains-ai restore --help

Paths above are positional arguments, not --out or --archive options. Source authority: tagged CLI, full family reference and withdrawn surface sets.