CLI Reference
Complete reference for all workbench CLI commands and flags.
Commands
| Command | Description |
|---|---|
wb run <plan> | Execute a plan with parallel agents |
wb merge -b <branch> | Merge completed-but-unmerged task branches |
wb preview <plan> | Dry-run: show parsed tasks and waves |
wb setup | Create .workbench/, install skills, and optionally create a profile |
wb status | Show active worktrees |
wb stop | Kill all running agent tmux sessions |
wb clean | Remove all workbench worktrees and wb/ branches |
wb profile init | Create profile.yaml from defaults |
wb profile show | Show resolved profile |
wb profile set <key> <value> | Update a profile field |
wb profile diff | Show differences from defaults |
wb run
The primary command. Parses a plan, creates isolated git worktrees, and dispatches agents in parallel.
wb run <plan.md> [options]Flags
| Flag | Description |
|---|---|
-j N | Max concurrent agents (default: 4) |
--max-retries N / -r N | Max fix cycles per failed stage (default: 2) |
--skip-test | Skip the test phase |
--skip-review | Skip the review phase |
--tdd | Test-driven: write tests first, then implement |
--agent CMD | Agent CLI command (default: claude) |
--no-tmux | Run agents as subprocesses instead of tmux |
--base BRANCH | Base branch to start from (default: main) |
--local | Branch from local ref instead of fetching origin |
-b NAME / --session-branch | Resume an existing session branch |
-w N / --start-wave | Skip already-completed waves |
--retry-failed | Auto-retry tasks that crashed (not those that exhausted fix retries) |
--fail-fast | Stop after the first wave with any failed tasks |
--only-failed | Skip completed tasks from a prior run (requires -b) |
--task ID | Run only specific tasks by ID or slug (repeatable) |
--cleanup | Remove worktrees after completion |
--keep-branches | Keep task branches after merging (default: auto-delete on success) |
--repo PATH | Repository path (auto-detected if omitted) |
--profile PATH | Use a specific profile.yaml |
--profile-name NAME | Use a named profile (profile.<name>.yaml) |
--*-directive TEXT | Override instructions for a specific agent role |
Examples
Run a plan with default settings:
wb run plan.mdRun with TDD mode and skip the review stage:
wb run plan.md --tdd --skip-reviewResume a previously interrupted session from wave 3:
wb run plan.md -b workbench-1 -w 3Retry only the tasks that failed in a previous run:
wb run plan.md -b workbench-1 --only-failedAdd custom reviewer instructions:
wb run plan.md --reviewer-directive "Focus on error handling and edge cases"wb merge
Merge completed-but-unmerged task branches into the session branch. Useful when tasks completed but merging was interrupted or skipped.
wb merge -b <session-branch> [options]Flags
| Flag | Description |
|---|---|
-b NAME / --session-branch | Session branch to merge into (required) |
--agent CMD | Agent CLI for conflict resolution (default: claude) |
--no-tmux | Run resolver agents as subprocesses instead of tmux |
--keep-branches | Keep task branches after merging |
--repo PATH | Repository path (auto-detected if omitted) |
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
| Flag | Description |
|---|---|
--agent NAME | Target platform: claude, gemini, cursor, codex, manual (auto-detected if omitted) |
--global | Install skills to user-level paths only (skip .workbench/ creation) |
--symlink | Symlink instead of copy (stays in sync with package updates) |
--profile | Also create a profile.yaml with the detected agent |
--update | Force-update skills to the latest version |
--repo PATH | Repository path (auto-detected if omitted) |
wb status
Shows active workbench worktrees.
wb status [--repo PATH]wb stop
Kill all running agent tmux sessions.
wb stop [options]Flags
| Flag | Description |
|---|---|
--cleanup | Also remove worktrees and wb/ branches |
--repo PATH | Repository path (auto-detected if omitted) |
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
| Flag | Description |
|---|---|
--yes | Skip confirmation prompt |
--repo PATH | Repository path (auto-detected if omitted) |
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]| Flag | Description |
|---|---|
--global | Create in ~/.workbench/ instead of .workbench/ |
--name NAME | Create a named profile (profile.<name>.yaml) |
--set KEY=VALUE | Set role fields inline (repeatable) |
--repo PATH | Repository path (auto-detected if omitted) |
wb profile show
Display the resolved profile configuration:
wb profile show [options]| Flag | Description |
|---|---|
--name NAME | Show a named profile |
--profile PATH | Path to a specific profile.yaml |
--repo PATH | Repository path (auto-detected if omitted) |
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| Flag | Description |
|---|---|
--global | Update ~/.workbench/ instead of local |
--name NAME | Update a named profile |
--repo PATH | Repository path (auto-detected if omitted) |
wb profile diff
Show differences between your current profile and the default:
wb profile diff [options]| Flag | Description |
|---|---|
--name NAME | Diff a named profile |
--profile PATH | Path to a specific profile.yaml |
--repo PATH | Repository path (auto-detected if omitted) |