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

Frontmatter-readable flags

Plans may declare these keys in a YAML frontmatter block (--- delimiters) at the top of the file. Frontmatter values act as defaults; explicit CLI flags always win. Unknown keys raise an error.

See Plan Frontmatter for the full format and examples.

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

Run only specific tasks by id or slug (repeatable):

wb run myplan --task token-service --task api-routes

Reference a plan by name (resolves to .workbench/myplan/plan.md):

wb run myplan -w 2
wb run myplan -b workbench-1 --only-incomplete

Resume a session, re-running every incomplete task:

wb resume workbench-1

Retry only incomplete tasks manually (use this if you need to override flags):

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

Add custom reviewer instructions:

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

wb resume

Sugar over wb run <plan> -b <session> --only-incomplete. Looks up the session in .workbench/<plan>/status.yaml (legacy .workbench/status-*.yaml is still read), finds the original plan via the recorded plan_source, and re-runs every task that isn't done + merged. Frontmatter is read from the plan referenced by the session's plan_source; CLI flags override frontmatter, same as wb run.

wb resume <session-branch> [options]

This includes tasks that failed AND tasks that never started (e.g., a crash before the wave reached them). For finer-grained control — wave ranges, directive overrides, selective tasks — use wb run directly.

Flags

Examples

wb resume workbench-1
wb resume workbench-1 --tdd       # if the original session was TDD
wb resume workbench-1 --no-tmux

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

Subcommands

wb plan copy-settings

Copy the current effective profile.yaml and agents.yaml into an existing plan folder, with a date-stamped header. Use this to freeze a plan's agent configuration at a point in time so it doesn't change when the project-level config evolves.

wb plan copy-settings <name>

This writes .workbench/<name>/profile.yaml and .workbench/<name>/agents.yaml from the current resolved config. You can also pass --copy-settings to wb plan to do this in the same step as generating the plan.

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

Generate a plan and freeze the current agent config into the plan folder:

wb plan "Add JWT auth" --name auth --copy-settings

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

cat .workbench/plan/plan.md      # review the generated plan
wb preview .workbench/plan/plan.md
wb run .workbench/plan/plan.md
# Or use the plan name directly (resolves to .workbench/<name>/plan.md)
wb preview plan
wb run plan

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

Examples

wb merge -b workbench-1                       # merge completed task branches
wb merge -b workbench-1 --push                # also push the session branch to origin
wb merge -b workbench-1 --push --review       # merge, run the branch review, open a PR on PASS
wb merge -b workbench-1 --review --skip-pr    # review but never open a PR

See Review & Pull Requests for the full requirements → review → PR flow.

wb final-review

Alias: wb review. Run a whole-branch review for a completed session. A requirements summarizer extracts a structured digest from the plan, then a branch reviewer and branch fixer loop until the review passes or --max-retries is exhausted.

On VERDICT: PASS, the review branch is merged back into the session branch and workbench opens a GitHub PR via gh pr create. On VERDICT: FAIL after all retries, no PR is created — the final report lists findings with file/line evidence and suggested fixes.

Artifacts land under .workbench/<plan-id>/wrap-up/<session>/:

• requirements.md — the requirements digest
• review.md — the review report
• pr-body.md — the PR title and body (written on PASS)

Each run appends an entry to the session's final_reviews list in .workbench/<plan-id>/status.yaml. wb status surfaces the latest verdict and PR URL (or review path on fail).

wb final-review workbench-1                       # default: open PR on PASS
wb final-review workbench-1 --skip-pr             # never open a PR
wb final-review workbench-1 --pr-title "My feat"  # override PR metadata

gh must be installed and authenticated for PR creation. When it isn't, the review still runs; the PR step prints a copy-pasteable gh pr create command instead of failing.

Flags

The summarizer, branch_reviewer, and fixer roles are configurable in profile.yaml like any other role (agent, directive). See Profiles and Review & Pull Requests.

wb pull-request

Open a GitHub PR for a session, with an AI-written title and description. The PR writer agent reads the plan context, git diff stat, commit log, and merged task titles to author a relevant PR body. Falls back to a plan-derived body if the agent fails.

Unlike wb final-review, this command skips the requirements review and goes straight to PR creation. Use it after a session is complete and already merged, when you don't need the branch review step.

wb pull-request <plan> [options]

<plan> can be a plan name (e.g. myfeature, resolved to .workbench/myfeature/plan.md) or a path to a plan.md file. If the plan has multiple sessions, specify which one with -b.

gh must be installed and authenticated for PR creation.

Flags

Examples

wb pull-request myfeature
wb pull-request myfeature -b workbench-3      # when plan has multiple sessions
wb pull-request myfeature --pr-title "Add JWT auth"
wb pull-request myfeature --pr-body-file pr-body.md   # skip PR writer, use file

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.

Group options

Pass --plan immediately after wb agents and before the subcommand:

wb agents --plan myfeature list
wb agents --plan myfeature add my-agent --command my-cli

When --plan is omitted, subcommands read and write .workbench/agents.yaml (the project-level file).

wb agents init

Create 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 --plan <name> init   # create plan-scoped agents.yaml

wb agents list

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

wb agents list [--repo PATH]
wb agents --plan <name> list   # show plan-scoped agents

wb agents show

Show the full configuration for a specific agent:

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

wb agents add

Add or update a custom agent adapter:

wb agents add <name> [options]
wb agents --plan <plan> add <name> [options]   # write to plan-scoped agents.yaml

wb agents remove

Remove a custom agent adapter:

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

wb conventions

Manage the shared conventions file at .workbench/conventions.md. The conventions file is loaded by every agent role (implementor, tester, reviewer, fixer, planner) and is the single place to record house style, libraries to prefer, things to avoid, and any other repo-wide guidance that should apply across all workbench-dispatched work.

See Conventions for what to put in the file and how it's injected into agent prompts.

wb conventions init

Create a starter .workbench/conventions.md with section headings and inline guidance to fill in. Errors if the file already exists (use wb conventions edit instead).

wb conventions init [options]

wb conventions init                # write a blank starter file
wb conventions init --generate     # have an agent draft it from the repo

wb conventions show

Print the current conventions file to stdout. Exits non-zero with a friendly message if no conventions file exists.

wb conventions show [--repo PATH]

wb conventions edit

Open .workbench/conventions.md in $EDITOR (falls back to vi). Creates the file from the starter template if it doesn't exist yet.

wb conventions edit [--repo PATH]

wb conventions delete

Remove .workbench/conventions.md. Prompts for confirmation unless --yes is passed.

wb conventions delete [--yes] [--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]

The key uses dot notation: <role>.<field> or <role>.<sub_mode>.<field>.

Roles: implementor, tester, reviewer, fixer, merger, planner

wb profile set implementor.agent gemini
wb profile set reviewer.agent claude
wb profile set tester.tdd.directive "Use pytest fixtures for shared setup."
wb profile set reviewer.followup.directive "Focus only on changes since last review."

wb profile diff

Show differences between your current profile and the default:

wb profile diff [options]