CLI Reference

Complete reference for all workbench CLI commands and flags.

Commands

wb run

The primary command. Parses a plan, creates isolated git worktrees, and dispatches agents in parallel.

wb run <plan.md> [options]

Flags

Examples

Run a plan with default settings:

wb run plan.md

Run with TDD mode and skip the review stage:

wb run plan.md --tdd --skip-review

Resume a previously interrupted session from wave 3 through the end:

wb run plan.md -b workbench-1 --start-wave 3

Run only a specific wave in an existing session:

wb run plan.md -b workbench-1 -w 2

Run a range of waves:

wb run plan.md -b workbench-1 --start-wave 2 --end-wave 4

Retry only the tasks that failed in a previous run:

wb run plan.md -b workbench-1 --only-failed

Add custom reviewer instructions:

wb run plan.md --reviewer-directive "Focus on error handling and edge cases"

wb plan

Dispatch a planner agent to generate a workbench plan. The planner surveys the repository, designs a task graph for parallel execution, and writes a plan markdown file you can review and run with wb run.

wb plan "<prompt>" [--from FILE] [options]

At least one of a prompt or --from is required.

Flags

Examples

Generate a plan from a prompt:

wb plan "Add JWT authentication to the FastAPI app"

Convert an existing spec into a workbench plan:

wb plan --from docs/auth-spec.md --name auth

Combine a prompt with an existing document as seed material:

wb plan "Focus on security and edge cases" --from existing-spec.md --name secure-auth

After a plan is written, the CLI prints the path and suggested next commands:

cat .workbench/plans/plan.md      # review the generated plan
wb preview .workbench/plans/plan.md
wb run .workbench/plans/plan.md

wb merge

Merge completed-but-unmerged task branches into the session branch. Useful when tasks completed but merging was interrupted or skipped. The plan is auto-detected from the session branch unless you specify --plan.

wb merge -b <session-branch> [options]

Flags

wb preview

Dry-run a plan. Shows parsed tasks, the dependency graph, and wave assignments without executing any code or creating worktrees.

wb preview <plan.md>

wb setup

Initialize a repository for workbench. Creates the .workbench/ directory, installs agent skill files, and optionally creates a profile.

wb setup [options]

Flags

wb status

Shows active workbench worktrees.

wb status [--repo PATH]

wb stop

Kill all running agent tmux sessions.

wb stop [options]

Flags

wb clean

Remove all workbench-created git worktrees and wb/ branches. Useful for reclaiming disk space after a run or cleaning up after interrupted sessions.

wb clean [options]

Flags

wb agents

Manage agent adapters — built-in and custom CLI integrations.

wb agents init

Create .workbench/agents.yaml pre-populated with configs for all built-in adapters (Claude, Gemini, Codex, Cursor, Copilot). Use as a starting point for customization.

wb agents init [--repo PATH]

wb agents list

List all available agents (built-in and custom):

wb agents list [--repo PATH]

wb agents show

Show the full configuration for a specific agent:

wb agents show <name> [--repo PATH]

wb agents add

Add or update a custom agent adapter:

wb agents add <name> [options]

wb agents remove

Remove a custom agent adapter:

wb agents remove <name> [--repo PATH]

wb profile

Manage agent profiles — saved configurations for which agent handles which pipeline role.

wb profile init

Create a profile from defaults:

wb profile init [options]

wb profile show

Display the resolved profile configuration:

wb profile show [options]

wb profile set

Update a profile field:

wb profile set <key> <value> [options]

Roles: implementor, tester, reviewer, fixer

wb profile set implementor gemini
wb profile set reviewer claude

wb profile diff

Show differences between your current profile and the default:

wb profile diff [options]