docs/cli-reference.md

CLI reference

Roark commands, flags, and examples.

Last updated 2026-07-25T07:13:47Z

Use the installed binary:

roark --help
roark --version

Or run from a source checkout:

bun run roark.ts --help

#Issue argument

Commands that accept an issue support:

123
https://github.com/owner/repo/issues/123
owner/repo#123

auto without an issue discovers eligible issues. auto with an issue targets that issue directly.

#Core commands

Command	Purpose
`roark init`	Initialize Roark in the current repository.
`roark auto [issue]`	Work on the next ready issue, or a specific issue, in a managed workspace and publish after all gates pass.
`roark do <issue>`	Run the complete issue workflow in the current checkout without publishing.
`roark continue <issue>`	Resume a stopped issue workflow and publish after all gates pass.
`roark status [issue]`	View workflow status and recovery information. Use `--all` for every known issue run.
`roark remove [issue ...]`	Interactively select managed workspaces to remove, or remove the listed issue workspaces. Use `--pr <n>` for PR workspaces and `--force` for dirty workspaces.
`roark review-pr <number>`	Review an existing open or draft PR without changing code; posts each review directly as its own comment by default.
`roark revise-pr <number>`	Address required review feedback on an existing open PR and push verified fixes when needed.
`roark curate-issues <issue>`	Write an issue creation plan from reviewer findings.
`roark create-issues <issue>`	Create approved GitHub issues from the curation plan. Dry-run unless `--yes`.

#Workspace commands

Command	Purpose
`roark workspace list`	List managed clone workspaces.
`roark workspace prune --older-than <duration>`	Remove old clean workspaces, for example `--older-than 30d`.

#Phase commands

Command	Purpose
`roark fetch <issue>`	Fetch the GitHub issue into `.roark/runs/issue/<number>/`.
`roark triage <issue>`	Run only the triage agent.
`roark plan <issue>`	Run only the implementation planning agent.
`roark implement <issue>`	Run only the implementation agent.
`roark review <issue>`	Run both review agents.
`roark fix <issue>`	Run only the fix agent.
`roark readiness <issue>`	Write the PR readiness result.

Phase commands are most useful for debugging. For normal work, prefer do, auto, or continue.

#Common options

Option	Applies to	Purpose
`--repo <owner/repo>`	GitHub-backed commands	Repository for `gh` issue and PR commands.
`--cwd <path>`	Most commands	Repository working directory. Defaults to current directory.
`--out <path>`	Workflow commands	Runs directory. Defaults to `.roark/runs`.
`--model <provider/id>`	Agent-backed phases	Optional Pi model override, for example `anthropic/claude-sonnet-4-5`.
`--thinking <level>`	Agent-backed phases	Thinking level override: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Unsupported levels are clamped by Pi to a supported level and reported.
`--max-fix-passes <n>`	`auto`, `do`, `continue`	Maximum automatic fix/review cycles. Defaults to `3`.
`--fix-pass <n>`	`fix`	Fix pass number.
`--attempt <n>`	issue, `continue`, `status`	Use a specific autorun attempt directory.
`--all`	`status`	Summarize all known issue runs.
`--force`	phase, implementation, fix, PR revision	Re-run phases or continue past supported dirty-tree preflights.
`--yes`	supported mutation paths	Continue past supported prompts or approve `create-issues` mutations.
`--verbose`	long-running agent commands	Show completed agent responses and detailed tool statistics.
`--no-title`	long-running agent commands	Disable Roark terminal-title management.
`-v`, `--version`	top-level only	Print the installed Roark version.
`-h`, `--help`	all commands	Show help.

#Live output

Long-running commands show the target, phase, pass, tool activity, elapsed time, verification status, artifact path, and result. Pass --verbose to print completed agent responses too. The short -v flag means --version.

In an interactive terminal, Roark updates the window title with the issue or PR, phase, pass, and repository. Pass --no-title to disable it. Redirected or piped output, CI, and TERM=dumb omit the title and ANSI sequences. Roark does not truncate this output to the terminal width. Warnings go to stderr.

Paths are relative to the repository or run directory when possible. Interactive output shortens long lines to fit the terminal. aggregate tool execution totals individual tool durations, so concurrent calls can make it larger than elapsed time.

#Autorun options

Option	Purpose
`--label <label>`	Auto eligibility label. Defaults to `ready-for-agent`.
`--skip-label <label>`	Auto skip label. Repeatable. Required workflow skip labels are still appended.
`--skip-labels <labels>`	Auto skip labels as a comma-separated list. Required workflow skip labels are still appended.
`--limit <n>`	Maximum number of eligible auto issues to claim. Defaults to `1`.
`--in-progress-label <label>`	Auto claim label and terminal continue cleanup label. Defaults to `agent-in-progress`.
`--assignee <login>`	GitHub user to assign when claiming. Defaults to the authenticated `gh` user.
`--no-assign`	Claim without assigning a user.
`--dry-run`	Print selected issues without claiming, switching branches, or running agents.
`--base-branch <branch>`	Auto issue branch base branch. Defaults to `main`.
`--verify <cmd>`	Verification command to run before publishing. Runs through `sh -c`.
`--failure-label <label>`	Label applied when readiness or verification fails. Defaults to `agent-failed`.
`--success-label <label>`	Label applied when a PR is opened. Defaults to `agent-pr-opened`.
`--remote <name>`	Git remote for pushing issue or PR branches. Defaults to `origin`.

#PR review options

Option	Purpose
`--verify <cmd>`	Override the verification command run before review. Uses `.roark/config.json` and then `bun run typecheck` when omitted, matching `revise-pr`.
`--no-comment`	Complete the local review without publishing a PR comment.

review-pr supports fork PRs through GitHub's pull ref and never edits, commits, or pushes. Configured hooks and verification run against the pinned PR checkout and may execute its code. Pass --repo when the Git origin does not identify the base repository.

#PR revision options

Option	Purpose
`--verify <cmd>`	Verification command before pushing the revision.
`--no-comment`	Do not post the terminal PR summary comment.
`--force`	Continue past supported dirty git preflight.

#Workspace options

Option	Purpose
`--pr <n>`	Select a managed PR workspace for removal; issue workspaces use positional numbers.
`--older-than <duration>`	Select clean workspaces older than a duration such as `30d`.
`--force`	Remove dirty workspaces. Use only after inspecting recoverable work.

#Examples

roark --version
roark init
roark do 123 --repo owner/repo
roark auto --repo owner/repo --limit 1 --dry-run
roark auto --repo owner/repo --limit 1
roark continue 123 --repo owner/repo --attempt 1
roark review-pr 456 --repo owner/repo
roark revise-pr 456 --repo owner/repo --verify "bun run check"
roark status --all --repo owner/repo
roark workspace list
roark workspace prune --older-than 30d
roark curate-issues 123 --repo owner/repo
roark create-issues 123 --repo owner/repo --yes