CLI Reference¶

This reference is generated from Batty's clap command tree.

`batty`¶

Hierarchical agent team system for software development

Hierarchical agent team system for software development

Usage: batty [OPTIONS] <COMMAND>

Commands:
  init                     Scaffold .batty/team_config/ with default team.yaml and prompt templates
  export-template          Export the current team config as a reusable template
  export-run               Export run state for debugging
  retro                    Generate a run retrospective
  start                    Start the team daemon and tmux session
  stop                     Stop the team daemon and kill the tmux session
  attach                   Attach to the running team tmux session
  status                   Show all team members and their states
  daemon-restart-if-stale  Safely rebuild and restart the daemon only when its binary is stale
  bench                    Prevent an engineer from receiving new auto-dispatch work
  unbench                  Remove an engineer from the durable bench list
  openclaw                 OpenClaw supervisor integration helpers for Batty
  send                     Send a message to an agent role (human → agent injection)
  assign                   Assign a task to an engineer (used by manager agent)
  validate                 Validate team config without launching
  config                   Show resolved team configuration
  board                    Show the kanban board
  inbox                    List inbox messages for a team member, or purge delivered inbox messages
  read                     Read a specific message from a member's inbox
  ack                      Acknowledge (mark delivered) a message in a member's inbox
  merge                    Merge an engineer's worktree branch into main
  task                     Manage workflow task state and metadata
  review                   Record a structured review disposition for a task
  completions              Generate shell completions
  nudge                    Per-intervention runtime toggles
  pause                    Pause nudges and standups
  resume                   Resume nudges and standups
  grafana                  Manage Grafana monitoring (setup, status, open)
  discord                  Configure Discord human communication
  telegram                 Set up Telegram bot for human communication
  project                  Manage the global Batty project registry for multi-project supervision
  load                     Estimate team load and show recent load history
  parity                   Show clean-room parity summary from PARITY.md
  verify                   Run clean-room equivalence verification from PARITY.md
  release                  Validate clean main, assemble release notes, and create a release tag
  queue                    Show pending dispatch queue entries
  dispatch                 Explain which engineer would receive the next dispatch
  cost                     Estimate current run cost from agent session files
  scale                    Dynamically scale team topology (add/remove agents)
  reload                   Trigger an explicit topology reload for the running daemon
  research                 Run autonomous evaluator-driven research missions
  doctor                   Dump diagnostic state from Batty state files
  worktree                 Inspect engineer worktree health
  metrics                  Show consolidated telemetry dashboard (tasks, cycle time, rates, agents)
  stress-test              Run a synthetic long-session stress harness with fault injection
  telemetry                Query the telemetry database for agent and task metrics
  chat                     Interactive chat with an agent via the shim protocol
  help                     Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

  -V, --version
          Print version

`batty ack`¶

Acknowledge (mark delivered) a message in a member's inbox

Acknowledge (mark delivered) a message in a member's inbox

Usage: batty ack [OPTIONS] <MEMBER> <ID>

Arguments:
  <MEMBER>
          Member name

  <ID>
          Message REF, ID, or ID prefix from `batty inbox` output

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty activity`¶

Internal activity-log maintenance commands

Internal activity-log maintenance commands

Usage: batty activity [OPTIONS] <COMMAND>

Commands:
  annotate-status  Add actor/source fields to the latest matching status activity entry
  help             Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty activity annotate-status`¶

Add actor/source fields to the latest matching status activity entry

Add actor/source fields to the latest matching status activity entry

Usage: batty activity annotate-status [OPTIONS] --source <SOURCE> <TASK_ID>

Arguments:
  <TASK_ID>
          Task id

Options:
      --source <SOURCE>
          Source command/module path

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty assign`¶

Assign a task to an engineer (used by manager agent)

Assign a task to an engineer (used by manager agent)

Usage: batty assign [OPTIONS] <ENGINEER> <TASK>

Arguments:
  <ENGINEER>
          Target engineer instance (e.g., "eng-1-1")

  <TASK>
          Task description

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty attach`¶

Attach to the running team tmux session

Attach to the running team tmux session

Usage: batty attach [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty bench`¶

Prevent an engineer from receiving new auto-dispatch work

Prevent an engineer from receiving new auto-dispatch work

Usage: batty bench [OPTIONS] <ENGINEER>

Arguments:
  <ENGINEER>
          Engineer instance (e.g., "eng-1-1")

Options:
      --reason <REASON>
          Optional reason recorded in bench.yaml and status output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty board`¶

Show the kanban board

Show the kanban board

Usage: batty board [OPTIONS] [COMMAND]

Commands:
  list     List board tasks in a non-interactive table
  summary  Show per-status task counts
  deps     Show dependency graph
  archive  Move done tasks to archive directory
  health   Show board health dashboard
  help     Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty board archive`¶

Move done tasks to archive directory

Move done tasks to archive directory

Usage: batty board archive [OPTIONS]

Options:
      --older-than <OLDER_THAN>
          Only archive tasks older than this (e.g. "7d", "24h", "2w", or ISO date)

          [default: 0s]

      --dry-run
          Show what would be archived without moving files

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty board deps`¶

Show dependency graph

Show dependency graph

Usage: batty board deps [OPTIONS]

Options:
      --format <FORMAT>
          Output format: tree (default), flat, or dot

          [default: tree]
          [possible values: tree, flat, dot]

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty board health`¶

Show board health dashboard

Show board health dashboard

Usage: batty board health [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty board list`¶

List board tasks in a non-interactive table

List board tasks in a non-interactive table

Usage: batty board list [OPTIONS]

Options:
      --status <STATUS>
          Filter tasks by status

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty board summary`¶

Show per-status task counts

Show per-status task counts

Usage: batty board summary [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty chat`¶

Interactive chat with an agent via the shim protocol

Interactive chat with an agent via the shim protocol

Usage: batty chat [OPTIONS]

Options:
      --agent-type <AGENT_TYPE>
          Agent type: claude, codex, kiro, generic

          [default: generic]

      --cmd <CMD>
          Shell command to launch the agent CLI (auto-detected from agent type if omitted)

      --cwd <CWD>
          Working directory for the agent

          [default: .]

      --sdk-mode
          Use SDK mode (NDJSON stdin/stdout) instead of PTY screen-scraping

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty completions`¶

Generate shell completions

Generate shell completions

Usage: batty completions [OPTIONS] <SHELL>

Arguments:
  <SHELL>
          Shell to generate completion script for

          [possible values: bash, zsh, fish]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty config`¶

Show resolved team configuration

Show resolved team configuration

Usage: batty config [OPTIONS]

Options:
      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty console-pane`¶

Internal: interactive shim pane bridge for tmux

Internal: interactive shim pane bridge for tmux

Usage: batty console-pane [OPTIONS] --project-root <PROJECT_ROOT> --member <MEMBER> --events-log-path <EVENTS_LOG_PATH> --pty-log-path <PTY_LOG_PATH>

Options:
      --project-root <PROJECT_ROOT>
          Project root directory

      --member <MEMBER>
          Member/agent id

      --events-log-path <EVENTS_LOG_PATH>
          Path to the shim event log

      --pty-log-path <PTY_LOG_PATH>
          Path to the shim PTY log

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty cost`¶

Estimate current run cost from agent session files

Estimate current run cost from agent session files

Usage: batty cost [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty daemon`¶

Internal: run the daemon loop (spawned by batty start)

Internal: run the daemon loop (spawned by `batty start`)

Usage: batty daemon [OPTIONS] --project-root <PROJECT_ROOT>

Options:
      --project-root <PROJECT_ROOT>
          Project root directory

      --resume
          Resume agent sessions from a previous run

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty daemon-restart-if-stale`¶

Safely rebuild and restart the daemon only when its binary is stale

Safely rebuild and restart the daemon only when its binary is stale

Usage: batty daemon-restart-if-stale [OPTIONS]

Options:
      --dry-run
          Show the safe restart plan without rebuilding or restarting

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty discord`¶

Configure Discord human communication

Configure Discord human communication

Usage: batty discord [OPTIONS] [COMMAND]

Commands:
  setup   Run the interactive Discord setup wizard
  status  Show the current Discord connection health
  help    Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty discord setup`¶

Run the interactive Discord setup wizard

Run the interactive Discord setup wizard

Usage: batty discord setup [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty discord status`¶

Show the current Discord connection health

Show the current Discord connection health

Usage: batty discord status [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty dispatch`¶

Explain which engineer would receive the next dispatch

Explain which engineer would receive the next dispatch

Usage: batty dispatch [OPTIONS]

Options:
      --explain
          Print routing reasons for the chosen engineer

      --task <TASK>
          Explain routing for a specific task id

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty doctor`¶

Dump diagnostic state from Batty state files

Dump diagnostic state from Batty state files

Usage: batty doctor [OPTIONS]

Options:
      --fix
          Remove orphan branches and worktrees after confirmation

      --yes
          Skip the cleanup confirmation prompt

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty export-run`¶

Export run state for debugging

Export run state for debugging

Usage: batty export-run [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty export-template`¶

Export the current team config as a reusable template

Export the current team config as a reusable template

Usage: batty export-template [OPTIONS] <NAME>

Arguments:
  <NAME>
          Template name

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty grafana`¶

Manage Grafana monitoring (setup, status, open)

Manage Grafana monitoring (setup, status, open)

Usage: batty grafana [OPTIONS] <COMMAND>

Commands:
  setup   Install Grafana and the SQLite datasource plugin, then start the service
  status  Check whether the Grafana server is reachable
  open    Open the Grafana dashboard in the default browser
  help    Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty grafana open`¶

Open the Grafana dashboard in the default browser

Open the Grafana dashboard in the default browser

Usage: batty grafana open [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty grafana setup`¶

Install Grafana and the SQLite datasource plugin, then start the service

Install Grafana and the SQLite datasource plugin, then start the service

Usage: batty grafana setup [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty grafana status`¶

Check whether the Grafana server is reachable

Check whether the Grafana server is reachable

Usage: batty grafana status [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty grafana-webhook`¶

Internal: receive Grafana webhook alerts and append them to alerts.log

Internal: receive Grafana webhook alerts and append them to alerts.log

Usage: batty grafana-webhook [OPTIONS] --project-root <PROJECT_ROOT>

Options:
      --project-root <PROJECT_ROOT>
          Project root directory

      --port <PORT>
          Local port to bind for webhook delivery

          [default: 8787]

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty inbox`¶

List inbox messages for a team member, or purge delivered inbox messages

List inbox messages for a team member, or purge delivered inbox messages

Usage: batty inbox [OPTIONS] [MEMBER]
       batty inbox <COMMAND>

Commands:
  purge  Purge delivered messages from inbox cur/ directories
  help   Print this message or the help of the given subcommand(s)

Arguments:
  [MEMBER]
          Member name (e.g., "architect", "manager-1", "eng-1-1")

Options:
  -n, --limit <LIMIT>
          Maximum number of recent messages to show

          [default: 20]

      --all
          Show all messages

      --raw
          Show all raw messages without digest collapsing

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty inbox purge`¶

Purge delivered messages from inbox cur/ directories

Purge delivered messages from inbox cur/ directories

Usage: batty inbox purge [OPTIONS] [ROLE]

Arguments:
  [ROLE]
          Role/member name to purge

Options:
      --all-roles
          Purge delivered messages for every inbox

      --before <BEFORE>
          Purge delivered messages older than this unix timestamp

      --older-than <OLDER_THAN>
          Purge delivered messages older than this duration (e.g. 24h, 7d, 2w)

      --all
          Purge all delivered messages

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty init`¶

Scaffold .batty/team_config/ with default team.yaml and prompt templates

Scaffold .batty/team_config/ with default team.yaml and prompt templates

Usage: batty init [OPTIONS]

Options:
      --template <TEMPLATE>
          Template to use for scaffolding

          Possible values:
          - solo:      Single agent, no hierarchy (1 pane)
          - pair:      Architect + 1 engineer pair (2 panes)
          - simple:    1 architect + 1 manager + 3 engineers (5 panes)
          - squad:     1 architect + 1 manager + 5 engineers with layout (7 panes)
          - large:     Human + architect + 3 managers + 15 engineers with Telegram (19 panes)
          - research:  PI + 3 sub-leads + 6 researchers — research lab style (10 panes)
          - software:  Human + tech lead + 2 eng managers + 8 developers — full product team (11 panes)
          - cleanroom: Clean-room workflow: decompiler + spec-writer + test-writer + implementer (4 panes)
          - batty:     Batty self-development: human + architect + manager + 4 Rust engineers (6 panes)
          - python:    Python-focused team with pytest-aware engineer prompts (5 panes)

      --from <FROM>
          Copy team config from $HOME/.batty/templates/<name>/

      --force
          Overwrite existing team config files

      --agent <AGENT>
          Default agent backend for all roles (claude, codex, kiro)

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help (see a summary with '-h')

`batty load`¶

Estimate team load and show recent load history

Estimate team load and show recent load history

Usage: batty load [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty merge`¶

Merge an engineer's worktree branch into main

Merge an engineer's worktree branch into main

Usage: batty merge [OPTIONS] <ENGINEER>

Arguments:
  <ENGINEER>
          Engineer instance name (e.g., "eng-1-1")

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty metrics`¶

Show consolidated telemetry dashboard (tasks, cycle time, rates, agents)

Show consolidated telemetry dashboard (tasks, cycle time, rates, agents)

Usage: batty metrics [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty nudge`¶

Per-intervention runtime toggles

Per-intervention runtime toggles

Usage: batty nudge [OPTIONS] <COMMAND>

Commands:
  disable  Disable an intervention at runtime
  enable   Re-enable a disabled intervention
  status   Show status of all interventions
  help     Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty nudge disable`¶

Disable an intervention at runtime

Disable an intervention at runtime

Usage: batty nudge disable [OPTIONS] <NAME>

Arguments:
  <NAME>
          Intervention name

          [possible values: replenish, triage, review, dispatch, utilization, owned-task]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty nudge enable`¶

Re-enable a disabled intervention

Re-enable a disabled intervention

Usage: batty nudge enable [OPTIONS] <NAME>

Arguments:
  <NAME>
          Intervention name

          [possible values: replenish, triage, review, dispatch, utilization, owned-task]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty nudge status`¶

Show status of all interventions

Show status of all interventions

Usage: batty nudge status [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty openclaw`¶

OpenClaw supervisor integration helpers for Batty

OpenClaw supervisor integration helpers for Batty

Usage: batty openclaw [OPTIONS] <COMMAND>

Commands:
  register   Write an OpenClaw project registration/config skeleton for Batty
  status     Show an operator-friendly Batty summary for OpenClaw supervision
  instruct   Send a high-level instruction into an allowed Batty role
  events     Export stable OpenClaw event envelopes for one project or all registered projects
  follow-up  Run configured OpenClaw follow-up/reminder workflows
  help       Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty openclaw events`¶

Export stable OpenClaw event envelopes for one project or all registered projects

Export stable OpenClaw event envelopes for one project or all registered projects

Usage: batty openclaw events [OPTIONS]

Options:
      --project-id <PROJECT_ID>
          Registered project identifier; defaults to the current project if it is registered

      --all-projects
          Read events across all registered projects that allow OpenClaw supervision

      --json
          Emit machine-readable JSON output

      --topic <TOPICS>
          Filter by stable public event topic

          [possible values: completion, review, stall, merge, escalation, delivery-failure, lifecycle]

      --role <ROLES>
          Filter by Batty role identifier

      --task-id <TASK_IDS>
          Filter by Batty task identifier

      --event-type <EVENT_TYPES>
          Filter by stable public event type

      --session-name <SESSION_NAMES>
          Filter by tmux/OpenClaw session name

      --since-ts <SINCE_TS>
          Include only events at or after this unix timestamp

      --limit <LIMIT>
          Trim the result set to the N most recent matching events

      --include-archived
          Include archived projects when reading from the project registry

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty openclaw follow-up`¶

Run configured OpenClaw follow-up/reminder workflows

Run configured OpenClaw follow-up/reminder workflows

Usage: batty openclaw follow-up [OPTIONS] <COMMAND>

Commands:
  run   Evaluate configured cron follow-ups and dispatch any due reminders
  help  Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty openclaw follow-up run`¶

Evaluate configured cron follow-ups and dispatch any due reminders

Evaluate configured cron follow-ups and dispatch any due reminders

Usage: batty openclaw follow-up run [OPTIONS]

Options:
      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty openclaw instruct`¶

Send a high-level instruction into an allowed Batty role

Send a high-level instruction into an allowed Batty role

Usage: batty openclaw instruct [OPTIONS] <ROLE> <MESSAGE>

Arguments:
  <ROLE>
          Target role, typically architect or manager

  <MESSAGE>
          High-level instruction text

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty openclaw register`¶

Write an OpenClaw project registration/config skeleton for Batty

Write an OpenClaw project registration/config skeleton for Batty

Usage: batty openclaw register [OPTIONS]

Options:
      --force
          Overwrite an existing config file

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty openclaw status`¶

Show an operator-friendly Batty summary for OpenClaw supervision

Show an operator-friendly Batty summary for OpenClaw supervision

Usage: batty openclaw status [OPTIONS]

Options:
      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty parity`¶

Show clean-room parity summary from PARITY.md

Show clean-room parity summary from PARITY.md

Usage: batty parity [OPTIONS]

Options:
      --detail
          Show the full parity table

      --gaps
          Show only behaviors with missing tests or implementation

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty pause`¶

Pause nudges and standups

Pause nudges and standups

Usage: batty pause [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project`¶

Manage the global Batty project registry for multi-project supervision

Manage the global Batty project registry for multi-project supervision

Usage: batty project [OPTIONS] <COMMAND>

Commands:
  register    Register a project in the global Batty/OpenClaw registry
  unregister  Remove a project from the registry
  list        List all registered projects
  get         Show one registered project by projectId
  start       Start one registered project by projectId
  stop        Stop one registered project by projectId
  restart     Restart one registered project by projectId
  status      Show lifecycle and health status for one registered project
  set-active  Set the active project used for implicit routing
  resolve     Resolve which project a message should route to
  help        Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project get`¶

Show one registered project by projectId

Show one registered project by projectId

Usage: batty project get [OPTIONS] <PROJECT_ID>

Arguments:
  <PROJECT_ID>
          Stable unique project identifier

Options:
      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project list`¶

List all registered projects

List all registered projects

Usage: batty project list [OPTIONS]

Options:
      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project register`¶

Register a project in the global Batty/OpenClaw registry

Register a project in the global Batty/OpenClaw registry

Usage: batty project register [OPTIONS] --project-id <PROJECT_ID> --name <NAME> --project-root <PROJECT_ROOT> --board-dir <BOARD_DIR> --team-name <TEAM_NAME> --session-name <SESSION_NAME>

Options:
      --project-id <PROJECT_ID>
          Stable unique project identifier

      --name <NAME>
          Operator-facing project name

      --alias <ALIASES>
          Alternate operator-facing aliases used for routing

      --project-root <PROJECT_ROOT>
          Repository root for the supervised project

      --board-dir <BOARD_DIR>
          Kanban board directory for the project

      --team-name <TEAM_NAME>
          Batty team name from team.yaml

      --session-name <SESSION_NAME>
          Explicit runtime session name

      --owner <OWNER>
          Optional owner or owning team

      --tag <TAGS>
          Tag metadata

      --channel-binding <CHANNEL_BINDINGS>
          Channel binding in the form <channel>=<binding>

      --thread-binding <THREAD_BINDINGS>
          Thread binding in the form <channel>=<binding>#<thread-binding>

      --allow-openclaw-supervision
          Allow OpenClaw supervision actions for this project

      --allow-cross-project-routing
          Allow cross-project routing for this project

      --allow-shared-service-routing
          Allow shared-service routing for this project

      --archived
          Mark the project archived at registration time

      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project resolve`¶

Resolve which project a message should route to

Resolve which project a message should route to

Usage: batty project resolve [OPTIONS] <MESSAGE>

Arguments:
  <MESSAGE>
          Message text to resolve

Options:
      --channel <CHANNEL>
          Optional channel provider name

      --binding <BINDING>
          Optional channel binding identifier

      --thread-binding <THREAD_BINDING>
          Optional thread binding identifier

      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project restart`¶

Restart one registered project by projectId

Restart one registered project by projectId

Usage: batty project restart [OPTIONS] <PROJECT_ID>

Arguments:
  <PROJECT_ID>
          Stable unique project identifier

Options:
      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project set-active`¶

Set the active project used for implicit routing

Set the active project used for implicit routing

Usage: batty project set-active [OPTIONS] <PROJECT_ID>

Arguments:
  <PROJECT_ID>
          Stable unique project identifier

Options:
      --channel <CHANNEL>
          Optional channel provider name for channel-scoped activation

      --binding <BINDING>
          Optional channel binding identifier for channel-scoped activation

      --thread-binding <THREAD_BINDING>
          Optional thread binding identifier for thread-scoped activation

      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project start`¶

Start one registered project by projectId

Start one registered project by projectId

Usage: batty project start [OPTIONS] <PROJECT_ID>

Arguments:
  <PROJECT_ID>
          Stable unique project identifier

Options:
      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project status`¶

Show lifecycle and health status for one registered project

Show lifecycle and health status for one registered project

Usage: batty project status [OPTIONS] <PROJECT_ID>

Arguments:
  <PROJECT_ID>
          Stable unique project identifier

Options:
      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project stop`¶

Stop one registered project by projectId

Stop one registered project by projectId

Usage: batty project stop [OPTIONS] <PROJECT_ID>

Arguments:
  <PROJECT_ID>
          Stable unique project identifier

Options:
      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty project unregister`¶

Remove a project from the registry

Remove a project from the registry

Usage: batty project unregister [OPTIONS] <PROJECT_ID>

Arguments:
  <PROJECT_ID>
          Stable unique project identifier

Options:
      --json
          Emit machine-readable JSON output

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty queue`¶

Show pending dispatch queue entries

Show pending dispatch queue entries

Usage: batty queue [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty read`¶

Read a specific message from a member's inbox

Read a specific message from a member's inbox

Usage: batty read [OPTIONS] <MEMBER> <ID>

Arguments:
  <MEMBER>
          Member name

  <ID>
          Message REF, ID, or ID prefix from `batty inbox` output

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty release`¶

Validate clean main, assemble release notes, and create a release tag

Validate clean main, assemble release notes, and create a release tag

Usage: batty release [OPTIONS]

Options:
      --tag <TAG>
          Override the git tag to create (default: v<Cargo.toml version>)

      --readiness
          Generate a release readiness artifact without creating a git tag

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty reload`¶

Trigger an explicit topology reload for the running daemon

Trigger an explicit topology reload for the running daemon

Usage: batty reload [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty research`¶

Run autonomous evaluator-driven research missions

Run autonomous evaluator-driven research missions

Usage: batty research [OPTIONS] <COMMAND>

Commands:
  start   Start a new research mission
  status  Show the current mission status
  ledger  Show the current mission ledger
  stop    Stop the current research mission
  help    Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty research ledger`¶

Show the current mission ledger

Show the current mission ledger

Usage: batty research ledger [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty research start`¶

Start a new research mission

Start a new research mission

Usage: batty research start [OPTIONS] --evaluator <EVALUATOR> <HYPOTHESIS>

Arguments:
  <HYPOTHESIS>
          Short hypothesis or mission description

Options:
      --evaluator <EVALUATOR>
          Evaluator shell command to run inside the worktree

      --format <FORMAT>
          Evaluator output contract

          [default: json]
          [possible values: json, exit-code]

      --keep-policy <KEEP_POLICY>
          Rule for keeping or discarding candidate iterations

          [default: pass-only]
          [possible values: pass-only, score-improvement, parity-improvement]

      --max-iterations <MAX_ITERATIONS>
          Stop after this many iterations

          [default: 10]

      --worktree <WORKTREE>
          Worktree to mutate during the mission

          [default: .]

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty research status`¶

Show the current mission status

Show the current mission status

Usage: batty research status [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty research stop`¶

Stop the current research mission

Stop the current research mission

Usage: batty research stop [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty resume`¶

Resume nudges and standups

Resume nudges and standups

Usage: batty resume [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty retro`¶

Generate a run retrospective

Generate a run retrospective

Usage: batty retro [OPTIONS]

Options:
      --events <EVENTS>
          Path to events.jsonl (default: .batty/team_config/events.jsonl)

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty review`¶

Record a structured review disposition for a task

Record a structured review disposition for a task

Usage: batty review [OPTIONS] <TASK_ID> <DISPOSITION> [FEEDBACK]

Arguments:
  <TASK_ID>
          Task id

  <DISPOSITION>
          Review disposition

          [possible values: approve, request-changes, reject]

  [FEEDBACK]
          Feedback text

Options:
      --reviewer <REVIEWER>
          Reviewer name (default: human)

          [default: human]

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty scale`¶

Dynamically scale team topology (add/remove agents)

Dynamically scale team topology (add/remove agents)

Usage: batty scale [OPTIONS] <COMMAND>

Commands:
  engineers       Set engineer instance count (scales up or down)
  add-manager     Add a new manager role
  remove-manager  Remove a manager role
  status          Show current topology (instance counts)
  help            Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty scale add-manager`¶

Add a new manager role

Add a new manager role

Usage: batty scale add-manager [OPTIONS] <NAME>

Arguments:
  <NAME>
          Name for the new manager role

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty scale engineers`¶

Set engineer instance count (scales up or down)

Set engineer instance count (scales up or down)

Usage: batty scale engineers [OPTIONS] <COUNT>

Arguments:
  <COUNT>
          Target number of engineers per manager

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty scale remove-manager`¶

Remove a manager role

Remove a manager role

Usage: batty scale remove-manager [OPTIONS] <NAME>

Arguments:
  <NAME>
          Name of the manager role to remove

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty scale status`¶

Show current topology (instance counts)

Show current topology (instance counts)

Usage: batty scale status [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty send`¶

Send a message to an agent role (human → agent injection)

Send a message to an agent role (human → agent injection)

Usage: batty send [OPTIONS] <ROLE> <MESSAGE>

Arguments:
  <ROLE>
          Target role name (e.g., "architect", "manager-1")

  <MESSAGE>
          Message to inject

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty shim`¶

Internal: run a shim process (spawned by batty chat or orchestrator)

Internal: run a shim process (spawned by `batty chat` or orchestrator)

Usage: batty shim [OPTIONS] --id <ID> --agent-type <AGENT_TYPE> --cmd <CMD> --cwd <CWD>

Options:
      --id <ID>
          Unique agent identifier

      --agent-type <AGENT_TYPE>
          Agent type: claude, codex, kiro, generic

      --cmd <CMD>
          Shell command to launch the agent CLI

      --cwd <CWD>
          Working directory for the agent

      --rows <ROWS>
          Terminal rows

          [default: 50]

      --cols <COLS>
          Terminal columns

          [default: 220]

      --pty-log-path <PTY_LOG_PATH>
          Path to write raw PTY output for tmux display panes

      --graceful-shutdown-timeout-secs <GRACEFUL_SHUTDOWN_TIMEOUT_SECS>
          Seconds to wait for auto-commit before force-killing

          [default: 5]

      --auto-commit-on-restart <AUTO_COMMIT_ON_RESTART>
          Auto-commit dirty worktrees before restart/shutdown

          [default: true]
          [possible values: true, false]

      --sdk-mode
          Use SDK mode (NDJSON stdin/stdout) instead of PTY screen-scraping

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty start`¶

Start the team daemon and tmux session

Start the team daemon and tmux session

Usage: batty start [OPTIONS]

Options:
      --attach
          Auto-attach to the tmux session after startup

  -q, --quiet
          Suppress informational output (errors still print)

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty status`¶

Show all team members and their states

Show all team members and their states

Usage: batty status [OPTIONS]

Options:
      --json
          Emit machine-readable JSON output

      --detail
          Include detailed telemetry-backed engineer profiles

      --health
          Show optional subsystem health and error-budget state

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty stop`¶

Stop the team daemon and kill the tmux session

Stop the team daemon and kill the tmux session

Usage: batty stop [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty stress-test`¶

Run a synthetic long-session stress harness with fault injection

Run a synthetic long-session stress harness with fault injection

Usage: batty stress-test [OPTIONS]

Options:
      --compact
          Run the full fault matrix on an accelerated compact timeline for CI

      --duration-hours <DURATION_HOURS>
          Virtual session duration in hours when not using compact mode

          [default: 8]

      --seed <SEED>
          Deterministic seed for fault scheduling and synthetic recovery timings

          [default: 1]

      --json-out <JSON_OUT>
          Override the JSON report output path

      --markdown-out <MARKDOWN_OUT>
          Override the Markdown report output path

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty task`¶

Manage workflow task state and metadata

Manage workflow task state and metadata

Usage: batty task [OPTIONS] <COMMAND>

Commands:
  transition  Transition a task to a new workflow state
  assign      Assign execution and/or review ownership
  review      Record a review disposition for a task
  update      Update workflow metadata fields
  auto-merge  Set per-task auto-merge override
  schedule    Set scheduled_for and/or cron_schedule on a task
  help        Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty task assign`¶

Assign execution and/or review ownership

Assign execution and/or review ownership

Usage: batty task assign [OPTIONS] <TASK_ID>

Arguments:
  <TASK_ID>
          Task id

Options:
      --execution-owner <EXECUTION_OWNER>
          Execution owner

      --review-owner <REVIEW_OWNER>
          Review owner

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty task auto-merge`¶

Set per-task auto-merge override

Set per-task auto-merge override

Usage: batty task auto-merge [OPTIONS] <TASK_ID> <ACTION>

Arguments:
  <TASK_ID>
          Task id

  <ACTION>
          Enable or disable auto-merge for this task

          [possible values: enable, disable]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty task review`¶

Record a review disposition for a task

Record a review disposition for a task

Usage: batty task review [OPTIONS] --disposition <DISPOSITION> <TASK_ID>

Arguments:
  <TASK_ID>
          Task id

Options:
      --disposition <DISPOSITION>
          Review disposition

          [possible values: approved, changes_requested, rejected]

      --feedback <FEEDBACK>
          Feedback text (stored and delivered for changes_requested)

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty task schedule`¶

Set scheduled_for and/or cron_schedule on a task

Set scheduled_for and/or cron_schedule on a task

Usage: batty task schedule [OPTIONS] <TASK_ID>

Arguments:
  <TASK_ID>
          Task id

Options:
      --at <AT>
          Scheduled datetime in RFC3339 format (e.g. 2026-03-25T09:00:00-04:00)

      --cron <CRON>
          Cron expression (e.g. '0 9 * * *')

      --clear
          Clear both scheduled_for and cron_schedule

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty task transition`¶

Transition a task to a new workflow state

Transition a task to a new workflow state

Usage: batty task transition [OPTIONS] <TASK_ID> <TARGET_STATE>

Arguments:
  <TASK_ID>
          Task id

  <TARGET_STATE>
          Target state

          [possible values: backlog, todo, in-progress, review, blocked, done, archived]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty task update`¶

Update workflow metadata fields

Update workflow metadata fields

Usage: batty task update [OPTIONS] <TASK_ID>

Arguments:
  <TASK_ID>
          Task id

Options:
      --branch <BRANCH>
          Worktree branch

      --commit <COMMIT>
          Commit sha

      --blocked-on <BLOCKED_ON>
          Blocking reason

      --clear-blocked
          Clear blocking fields

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty telegram`¶

Set up Telegram bot for human communication

Set up Telegram bot for human communication

Usage: batty telegram [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty telemetry`¶

Query the telemetry database for agent and task metrics

Query the telemetry database for agent and task metrics

Usage: batty telemetry [OPTIONS] <COMMAND>

Commands:
  summary  Show session summaries
  agents   Show per-agent performance metrics
  tasks    Show per-task lifecycle metrics
  reviews  Show review pipeline metrics (auto-merge rate, rework, latency)
  events   Show recent events from the telemetry database
  help     Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty telemetry agents`¶

Show per-agent performance metrics

Show per-agent performance metrics

Usage: batty telemetry agents [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty telemetry events`¶

Show recent events from the telemetry database

Show recent events from the telemetry database

Usage: batty telemetry events [OPTIONS]

Options:
  -n, --limit <LIMIT>
          Maximum number of events to show

          [default: 50]

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty telemetry reviews`¶

Show review pipeline metrics (auto-merge rate, rework, latency)

Show review pipeline metrics (auto-merge rate, rework, latency)

Usage: batty telemetry reviews [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty telemetry summary`¶

Show session summaries

Show session summaries

Usage: batty telemetry summary [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty telemetry tasks`¶

Show per-task lifecycle metrics

Show per-task lifecycle metrics

Usage: batty telemetry tasks [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty unbench`¶

Remove an engineer from the durable bench list

Remove an engineer from the durable bench list

Usage: batty unbench [OPTIONS] <ENGINEER>

Arguments:
  <ENGINEER>
          Engineer instance (e.g., "eng-1-1")

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty validate`¶

Validate team config without launching

Validate team config without launching

Usage: batty validate [OPTIONS]

Options:
      --show-checks
          Show all individual checks with pass/fail status

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty verify`¶

Run clean-room equivalence verification from PARITY.md

Run clean-room equivalence verification from PARITY.md

Usage: batty verify [OPTIONS]

Options:
  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty watchdog`¶

Internal: run the daemon watchdog supervisor (spawned by batty start)

Internal: run the daemon watchdog supervisor (spawned by `batty start`)

Usage: batty watchdog [OPTIONS] --project-root <PROJECT_ROOT>

Options:
      --project-root <PROJECT_ROOT>
          Project root directory

      --resume
          Resume agent sessions from a previous run

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

`batty worktree`¶

Inspect engineer worktree health

Inspect engineer worktree health

Usage: batty worktree [OPTIONS]

Options:
      --health
          Show the current worktree health report

  -v, --verbose...
          Verbosity level (-v, -vv, -vvv)

  -h, --help
          Print help

CLI Reference¶

batty¶

batty ack¶

batty activity¶

batty activity annotate-status¶

batty assign¶

batty attach¶

batty bench¶

batty board¶

batty board archive¶

batty board deps¶

batty board health¶

batty board list¶

batty board summary¶

batty chat¶

batty completions¶

batty config¶

batty console-pane¶

batty cost¶

batty daemon¶

batty daemon-restart-if-stale¶

batty discord¶

batty discord setup¶

batty discord status¶

batty dispatch¶

batty doctor¶

batty export-run¶

batty export-template¶

batty grafana¶

batty grafana open¶

batty grafana setup¶

batty grafana status¶

batty grafana-webhook¶

batty inbox¶

batty inbox purge¶

batty init¶

batty load¶

batty merge¶

batty metrics¶

batty nudge¶

batty nudge disable¶

batty nudge enable¶

batty nudge status¶

batty openclaw¶

batty openclaw events¶

batty openclaw follow-up¶

batty openclaw follow-up run¶

batty openclaw instruct¶

batty openclaw register¶

batty openclaw status¶

batty parity¶

batty pause¶

batty project¶

batty project get¶

batty project list¶

batty project register¶

batty project resolve¶

batty project restart¶

batty project set-active¶

batty project start¶

batty project status¶

batty project stop¶

batty project unregister¶

batty queue¶

batty read¶

batty release¶

batty reload¶

batty research¶

batty research ledger¶

batty research start¶

batty research status¶

batty research stop¶

batty resume¶

batty retro¶

batty review¶

batty scale¶

batty scale add-manager¶

batty scale engineers¶

batty scale remove-manager¶

batty scale status¶