CLI Operations Guide

Guide for operating agent sessions from the CommandMate CLI. These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate other agents in parallel.

Prerequisites

CommandMate server must be running (commandmate start --daemon)
Target worktrees must be registered (visible in the browser UI sidebar)

Server Port

CLI connects to localhost:3000 by default. Use CM_PORT for a different port:

CM_PORT=3011 commandmate ls

Authentication

If the server was started with --auth, set the CM_AUTH_TOKEN environment variable:

CM_AUTH_TOKEN=your-token commandmate ls

Running from Development Environment

No global install required:

npm run build:cli
node bin/commandmate.js ls

Command Reference

Command	Purpose
`commandmate ls`	List worktrees with status
`commandmate send`	Send a message to an agent
`commandmate wait`	Wait for agent completion
`commandmate respond`	Respond to a prompt
`commandmate capture`	Get terminal output
`commandmate auto-yes`	Control auto-yes
`commandmate report`	Generate, show, and list daily reports
`commandmate update`	Update CommandMate itself (stop, update, restart)

commandmate ls

List worktrees with their status.

commandmate ls                          # Table format
commandmate ls --json                   # JSON (for agents)
commandmate ls --quiet                  # IDs only (one per line)
commandmate ls --branch feature/        # Filter by branch prefix
commandmate ls --id anvil-             # Filter by worktree id prefix

About --id: Worktree IDs are <repo>-<branch> slugs (e.g. anvil-develop), and --id front-matches on that ID. --branch and --id are applied independently; specifying both applies both (AND). When the same branch name (e.g. develop) exists across multiple repositories, an ID prefix such as --id anvil- narrows the result to a single repository's worktree. The front-match is case-sensitive and does not guarantee uniqueness (--id anvil-develop may also match anvil-develop-2). To pin down exactly one worktree, pipe --quiet output through grep -x or pass a prefix that is already unique.

Output Example

ID                                               NAME                  STATUS   DEFAULT
-----------------------------------------------  --------------------  -------  ------
localllm-test-main                               main                  ready    claude
mycodebranchdesk-develop                         develop               running  claude
mycodebranchdesk-feature-518-worktree            feature/518-worktree  ready    claude
mycodebranchdesk-main                            main                  idle     claude

STATUS Column

Status	Meaning
`idle`	Session not started
`ready`	Session running, waiting for input (task completed)
`running`	Agent executing a task
`waiting`	Confirmation prompt active (Yes/No, etc.)

commandmate send

Send a message to a worktree's agent (async). Starts the session automatically if not running.

commandmate send <worktree-id> "<message>"
commandmate send <worktree-id> "<message>" --agent codex
commandmate send <worktree-id> "<message>" --auto-yes --duration 3h

Options

Option	Description	Default
`--agent <id>`	Agent type (claude, codex, gemini, vibe-local, opencode)	claude
`--auto-yes`	Enable auto-yes before sending	-
`--duration <d>`	Auto-yes duration (1h, 3h, 8h)	1h
`--stop-pattern <p>`	Auto-yes stop condition (regex)	-

Finding Worktree IDs

WT=$(commandmate ls --branch feature/101 --quiet)
# Or disambiguate the same branch across repositories by worktree id prefix:
WT=$(commandmate ls --id anvil- --quiet)
commandmate send "$WT" "Implement this"

commandmate wait

Block until the agent completes or a prompt is detected.

commandmate wait <worktree-id> --timeout 300
commandmate wait <id1> <id2> --timeout 600          # Multiple worktrees
commandmate wait <worktree-id> --on-prompt human     # Human responds via UI
commandmate wait <worktree-id> --stall-timeout 120

Exit Codes

Code	Meaning	Next Action
0	Completed (agent idle)	`capture` to get results
10	Prompt detected (`--on-prompt agent`)	`respond`, then `wait` again
124	Timeout	`capture` to check status

--on-prompt Modes

Mode	Behavior
`agent` (default)	Returns immediately with exit 10 + prompt JSON on stdout
`human`	Keeps blocking until human responds via browser UI

Progress Output

Progress is written to stderr. Only the final result (JSON) goes to stdout.

commandmate respond

Respond to an agent's prompt.

commandmate respond <worktree-id> "yes"          # Yes/No
commandmate respond <worktree-id> "2"            # Multiple choice (number)
commandmate respond <worktree-id> "text"         # Free text
commandmate respond <worktree-id> "yes" --agent claude

Exit Codes

Code	Meaning
0	Response sent successfully
99	Prompt already dismissed (`prompt_no_longer_active`)

commandmate capture

Get the current terminal output from a worktree.

commandmate capture <worktree-id>                # Plain text
commandmate capture <worktree-id> --json          # JSON with status info
commandmate capture <worktree-id> --agent codex

JSON Output Fields

{
  "isRunning": true,
  "sessionStatus": "ready",
  "cliToolId": "claude",
  "lineCount": 42,
  "isPromptWaiting": false,
  "autoYes": { "enabled": false, "expiresAt": null }
}

commandmate auto-yes

Control auto-yes (automatic prompt response) individually.

commandmate auto-yes <worktree-id> --enable --duration 3h
commandmate auto-yes <worktree-id> --enable --stop-pattern "error"
commandmate auto-yes <worktree-id> --disable

commandmate report

Generate, show, and list daily reports (a summary of the day's agent activity, Issue #636). While the server is running, the selected AI tool generates the report from registered session history.

commandmate report generate                       # Generate today's report (claude)
commandmate report generate --date 2026-06-21      # Specific date
commandmate report generate --tool codex           # Choose AI tool
commandmate report generate --template <id>        # Use a template as the instruction
commandmate report generate --instruction "Summarize"  # Custom instruction

commandmate report show                            # Show today's report
commandmate report show --date 2026-06-21 --json   # Specific date + JSON

commandmate report list                            # List the last 7 days
commandmate report list --days 30                  # List the last 30 days
commandmate report list --json                     # JSON output

Subcommands

Subcommand	Purpose
`generate`	Generate the report for a date and print its content to stdout
`show`	Show an existing report (`No report found` if not generated)
`list`	List report presence, message count, and tool for the last N days

generate Options

Option	Description	Default
`--date <date>`	Target date (`YYYY-MM-DD`)	today
`--tool <tool>`	AI tool to use (claude, codex, copilot)	claude
`--model <model>`	Model name (for copilot)	-
`--template <id>`	Template ID used as the instruction	-
`--instruction <text>`	Custom instruction text (alternative to `--template`)	-
`--token <token>`	Auth token (prefer the `CM_AUTH_TOKEN` env var)	-

show / list Options

Option	Description	Default
`--date <date>` (show)	Target date (`YYYY-MM-DD`)	today
`--days <days>` (list)	Number of days to list	7
`--json`	JSON output	-
`--token <token>`	Auth token (prefer the `CM_AUTH_TOKEN` env var)	-

Note: --date accepts only YYYY-MM-DD. An invalid format exits with code 2 (CONFIG_ERROR). --tool must be one of claude / codex / copilot, and --days must be at least 1.

list Output Example

2026-06-21  [report] tool=claude  messages=12
2026-06-20  [no report]  messages=3
2026-06-19  [report] tool=codex  messages=8

commandmate update

Update CommandMate itself to the latest version (Issue #1194). In a global install it runs stop, npm install -g commandmate@latest, restart, and a readiness check in one command. Unlike the other commands here, it acts on the npm registry and the local daemon rather than on a worktree (there is no --token flag; the readiness check resolves its URL from .env / CM_PORT and sends CM_AUTH_TOKEN as a bearer token when it is set).

commandmate update            # Update with a confirmation prompt
commandmate update --check    # Only report versions (changes nothing)
commandmate update --yes      # Skip the confirmation prompt (required without a TTY)

Options

Option	Description
`--check`	Print versions only. No install, stop or restart (exits 5 only if the registry query fails)
`-y, --yes`	Skip the confirmation prompt. Required without a TTY (otherwise exits 2)

--check Output

Current: v0.9.0
Latest: v0.10.0
Update available: yes

When the Update Is Skipped

Each of these prints a message and exits 0 without changing anything.

Condition	Behavior
Already up to date	Prints `Already up to date`
Local version is newer	Skips (never downgrades)
Local or latest is a prerelease	Skips (versions are not comparable)
Not installed globally (git clone)	Prints the manual steps (`git pull`, `npm install`, `npm run build:all`, restart)

Exit Codes

Code	Name	Meaning
0	SUCCESS	Updated, skipped, cancelled, or `--check` (including a degraded readiness check)
2	CONFIG_ERROR	No TTY and `--yes` was not passed
3	START_FAILED	Update succeeded but the restarted server could not be verified (no rollback needed)
4	STOP_FAILED	The server could not be stopped; aborted without changing anything
5	UPDATE_FAILED	Registry query, `npm install -g`, or version verification failed
99	UNEXPECTED_ERROR	Unexpected error

Caveats

Startup options are not restored: after the restart the server uses only the settings in .env. If you used --auth, --auth-expire, --cert, --key, --allow-http, --allowed-ips, --trust-proxy, --port or --dev, start it again manually (--auth generates a new token on every start).
Worktree servers (--issue) are out of scope: they are neither stopped nor restarted. npm install -g replaces the package directory (dist/, .next/), so a running worktree server may crash. Run commandmate stop --issue <number> before updating and commandmate start --issue <number> afterwards. The command warns when it detects running worktree servers.
If the main server was not running: it is updated but not started.
With auth, IP restrictions, or a self-signed certificate: the readiness check degrades to "the server responds" and exits 0 with a warning. Set CM_AUTH_TOKEN for the strict check.
EACCES: do not re-run with sudo. Fix the npm global directory permissions as described in the CLI setup guide.
Rollback: on failure the command prints npm install -g commandmate@<previous-version>.

Typical Workflows

Basic: send, wait, capture

WT=$(commandmate ls --branch feature/101 --quiet)
commandmate send "$WT" "Implement Issue #101 with TDD"
commandmate wait "$WT" --timeout 600
commandmate capture "$WT"

With Auto-Yes

WT=$(commandmate ls --branch feature/101 --quiet)
commandmate send "$WT" "Implement Issue #101" --auto-yes --duration 3h
commandmate wait "$WT" --timeout 1800
commandmate auto-yes "$WT" --disable
commandmate capture "$WT" --json

Prompt Response Loop

WT=$(commandmate ls --branch feature/101 --quiet)
commandmate send "$WT" "Refactor this module"

while true; do
  commandmate wait "$WT" --timeout 600 --on-prompt agent
  EXIT_CODE=$?

  if [ $EXIT_CODE -eq 0 ]; then
    echo "Done"
    break
  elif [ $EXIT_CODE -eq 10 ]; then
    # Prompt detected — auto-respond
    commandmate respond "$WT" "yes"
  elif [ $EXIT_CODE -eq 124 ]; then
    echo "Timeout"
    break
  fi
done

commandmate capture "$WT"

Parallel Worktrees

WT1=$(commandmate ls --branch feature/101 --quiet)
WT2=$(commandmate ls --branch feature/102 --quiet)

commandmate send "$WT1" "Implement #101" --auto-yes
commandmate send "$WT2" "Implement #102" --auto-yes --agent codex

commandmate wait "$WT1" "$WT2" --timeout 1800

commandmate capture "$WT1" --json
commandmate capture "$WT2" --json

Troubleshooting

Server not reachable

Error: Server is not running. Start it with: commandmate start

Cause: CommandMate server is not running, or the port is different.

Fix:

commandmate start --daemon

# If using a different port:
CM_PORT=3011 commandmate ls

Worktree ID not found

Error: Resource not found. Check the worktree ID.

Cause: The specified ID is not registered in the server.

Fix:

# Check registered IDs
commandmate ls --quiet

# Sync worktrees (if newly created)
curl -s -X POST http://localhost:3000/api/repositories/sync

wait keeps timing out

Cause: Agent is still processing, or has encountered an error.

Fix:

# Check current state
commandmate capture <id> --json

# Increase timeout
commandmate wait <id> --timeout 3600

# Check directly via browser UI at http://localhost:3000

respond returns "prompt_no_longer_active"

Warning: Response may not have been applied. Reason: prompt_no_longer_active

Cause: The prompt has already been dismissed (auto-yes responded, or timing mismatch).

Fix: No action needed. The agent continues normally. Proceed with wait.

Invalid duration / agent errors

Error: Invalid duration. Must be one of: 1h, 3h, 8h
Error: Invalid agent. Must be one of: claude, codex, gemini, vibe-local, opencode

Fix: Use one of the allowed values listed in the error message.

Connecting to an authenticated server

If the server was started with --auth, pass the token via environment variable or flag:

# Recommended: environment variable (not visible in process list)
CM_AUTH_TOKEN=your-token commandmate ls

# Alternative: --token flag (visible in process list — use with caution)
commandmate ls --token your-token

Exit Codes

Code	Name	Meaning
0	SUCCESS	Completed successfully
1	DEPENDENCY_ERROR	Server not running
2	CONFIG_ERROR	Validation error (invalid agent, duration, etc.)
3	START_FAILED	Failed to start or verify the server (`start` / `update`)
4	STOP_FAILED	Failed to stop the server (`stop` / `update`)
5	UPDATE_FAILED	Update failed (`update`: registry query / `npm install -g` / version verification)
10	PROMPT_DETECTED	Prompt detected during wait
99	UNEXPECTED_ERROR	Unexpected error / resource not found
124	TIMEOUT	Wait timeout exceeded

FilesExpand file tree

cli-operations-guide.md

Latest commit

History

cli-operations-guide.md

File metadata and controls

CLI Operations Guide

Prerequisites

Server Port

Authentication

Running from Development Environment

Command Reference

commandmate ls

Output Example

STATUS Column

commandmate send

Options

Finding Worktree IDs

commandmate wait

Exit Codes

--on-prompt Modes

Progress Output

commandmate respond

Exit Codes

commandmate capture

JSON Output Fields

commandmate auto-yes

commandmate report

Subcommands

generate Options

show / list Options

list Output Example

commandmate update

Options

--check Output

When the Update Is Skipped

Exit Codes

Caveats

Typical Workflows

Basic: send, wait, capture

With Auto-Yes

Prompt Response Loop

Parallel Worktrees

Troubleshooting

Server not reachable

Worktree ID not found

wait keeps timing out

respond returns "prompt_no_longer_active"

Invalid duration / agent errors

Connecting to an authenticated server

Exit Codes