Command reference
The most relevant current Switchman CLI commands. Run any command with --help to see full options.
Current first-run flow
| Command | Description |
|---|---|
| switchman quickcheck | Check repo readiness and print one exact next command. |
| switchman start "goal" | Fastest guided path. Creates or refreshes workspaces, local MCP config, and task planning for a new run. |
| switchman start "goal" --agents 4 --yes | Run the guided start flow non-interactively with a specific agent count. |
| switchman session-summary | Show a compact summary of what Switchman coordinated in the recent session. |
Setup & verification
| Command | Description |
|---|---|
| switchman setup --agents N | Create N agent workspaces, set up the coordination database, and write MCP config files. Run from your repo root. |
| switchman verify-setup | Check that the database, workspaces, and MCP config are all wired correctly. |
| switchman init | Initialise Switchman in the current git repo without creating extra workspaces. |
| switchman demo | Run a self-contained demo showing conflict prevention in a throwaway repo. |
| switchman demo --path /tmp/demo | Run the demo at a specific path. |
Status & monitoring
| Command | Description |
|---|---|
| switchman status | Show the full repo dashboard — health, active agents, blocked items, queue state, and next actions. |
| switchman status --watch | Live-updating dashboard. Refreshes automatically as agents work. |
| switchman status --json | Output status as JSON for scripting. |
| switchman scan | Scan all worktrees for conflicts, unclaimed changes, and stale work. |
| switchman explain claim <file> | Explain who owns a file and what task they are working on. |
| switchman explain queue <item-id> | Explain why a queue item is blocked, retrying, or ready. |
| switchman explain stale --pipeline <pipeline-id> | Explain stale waves and which tasks need to be retried. |
| switchman explain landing <pipeline-id> | Explain the current landing branch or recovery state for a pipeline. |
| switchman monitor status | Check the background rogue-edit monitor. |
Tasks
| Command | Description |
|---|---|
| switchman task add "title" --priority N | Add a task to the queue. Priority 1–10, higher = picked up first. |
| switchman task list | List all tasks with their status and priority. |
| switchman task next --worktree <name> | Quickly get and lease the next pending task for a workspace. |
| switchman task retry <task-id> | Return a failed or stale-completed task to pending. |
| switchman task retry-stale --pipeline <pipeline-id> | Reset the stale tasks for one pipeline back to pending together. |
| switchman task done <task-id> | Mark a task as complete. |
| switchman task fail <task-id> | Mark a task as failed and requeue it. |
Leases
| Command | Description |
|---|---|
| switchman lease next --worktree <name> | Claim the next pending task for a worktree. Returns the task and lease ID. |
| switchman lease heartbeat <lease-id> | Refresh a lease. Must be called at least every 60 seconds to keep the lease active. |
| switchman lease reap | Expire all stale leases and requeue their tasks. |
| switchman lease list | List all active leases. |
| switchman lease policy | Show the current stale-lease policy. |
| switchman lease policy set | Update automatic lease-reaping behaviour for the repo. |
File claims
| Command | Description |
|---|---|
| switchman claim <task-id> <worktree> <files...> | Claim one or more files for a task and worktree. Fails if any file is already claimed. |
| switchman claim --force <worktree> <files...> | Override an existing claim. Use only for operator-led recovery — not normal operation. |
| switchman release <task-id> | Release active file claims for a task during manual recovery. |
| switchman write <path> <content> | Write through the governed gateway so claim rules are enforced. |
| switchman wrap <command...> | Run a shell command through Switchman’s enforcement layer. |
Merge queue
| Command | Description |
|---|---|
| switchman queue add <branch> | Add a finished branch to the merge queue. |
| switchman queue add --worktree <name> | Add a finished worktree branch to the merge queue. |
| switchman queue add --pipeline <pipeline-id> | Queue a pipeline’s inferred landing branch, including synthetic landing branches when needed. |
| switchman queue list | List queue items with retry and escalation state. |
| switchman queue status | Show the merge queue and each item's readiness. |
| switchman queue run | Process the queue — land each branch onto main in priority order. |
| switchman queue run --follow-plan | Only run queue items that are currently in the land_now lane. |
| switchman queue run --merge-budget N | Land at most N branches in this run. |
| switchman queue retry <item-id> | Retry a blocked or held queue item after intervention. |
| switchman queue remove <item-id> | Remove an item from the queue. |
Pipelines & governed landing
| Command | Description |
|---|---|
| switchman pipeline start "title" | Create a tracked pipeline and split one goal into structured subtasks. |
| switchman pipeline exec <pipeline-id> "/path/to/agent-command" | Run a pipeline through one agent command and record structured outcomes. |
| switchman pipeline status <pipeline-id> | Show what is running, blocked, policy-gated, or ready to land. |
| switchman pipeline pr <pipeline-id> | Generate a PR-ready summary for the pipeline. |
| switchman pipeline bundle <pipeline-id> | Export reviewer-ready pipeline artifacts to disk. |
| switchman pipeline comment <pipeline-id> | Post or update the pipeline landing summary on a PR. |
| switchman pipeline sync-pr <pipeline-id> | Bundle artifacts, update the PR comment, and write GitHub outputs in one step. |
| switchman pipeline publish <pipeline-id> | Create the hosted PR once the landing state is ready. |
| switchman pipeline land <pipeline-id> | Materialize or inspect the landing branch for a pipeline. |
| switchman pipeline land <pipeline-id> --refresh | Refresh a stale synthetic landing branch after branches moved. |
| switchman pipeline land <pipeline-id> --recover | Open a guided recovery worktree for landing conflicts. |
| switchman pipeline land <pipeline-id> --resume | Resume landing after recovery work is committed. |
| switchman pipeline land <pipeline-id> --cleanup | Clean up temporary landing recovery resources. |
Gate, policy & CI
| Command | Description |
|---|---|
| switchman gate ci | Run the repo gate — checks for conflicts, unclaimed changes, stale worktrees, and compliance issues. |
| switchman gate ci --github | Run the gate with GitHub Actions output formatting. |
| switchman gate install-ci | Install a GitHub Actions workflow that runs the gate on every push and PR. |
| switchman policy init | Write a starter enforcement policy for generated-path exceptions. |
| switchman policy init-change | Write a starter change policy for governed domains like auth, payments, and schema. |
| switchman policy show-change | Show the active change policy for the repo. |
| switchman policy override <pipeline-id> --task-types tests --reason "why" | Record an explicit policy override for a pipeline requirement. |
| switchman policy list-overrides <pipeline-id> | List policy overrides for a pipeline. |
Pro commands
| Command | Description |
|---|---|
| switchman login | Sign in with GitHub to activate your Pro licence. |
| switchman login --status | Check your current plan, email, and renewal date. |
| switchman logout | Sign out and remove saved credentials. |
| switchman upgrade | Open switchman.dev/pro in your browser. |
| switchman team invite <email> | Invite a teammate to your Pro team. Returns an invite token. |
| switchman login --invite <token> | Accept a team invite and join the shared coordination. |
| switchman team list | List all team members and their status. |
| switchman plan "goal" | Generate a parallel task plan from a goal description. Pro only. |
| switchman plan "goal" --apply | Create the planned tasks in the queue. |
| switchman plan --issue 47 | Generate a plan directly from a GitHub issue. |
| switchman plan --issue 47 --apply --comment | Apply the issue plan and comment the summary back to the issue or PR. |
Utilities
| Command | Description |
|---|---|
| switchman claude refresh | Generate or update CLAUDE.md with Switchman coordination instructions. |
| switchman mcp install --windsurf | Install MCP config for Windsurf. |
| switchman audit verify | Verify the integrity of the audit trail. |
| switchman advanced brew-formula --sha256 <sha> --output Formula/switchman-dev.rb | Generate the Homebrew formula used during releases. |
| switchman telemetry status | Check whether anonymous telemetry is enabled. |
| switchman telemetry enable | Enable anonymous usage telemetry. |
| switchman telemetry disable | Disable anonymous usage telemetry. |
| switchman telemetry test | Send one test telemetry event and report whether delivery succeeded. |