CLI reference
Roark commands, flags, and examples.
Last updated
Use the installed binary:
roark --help
roark --versionOr 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#123auto 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. |
--fast |
Agent-backed phases | Use the fast thinking profile. Cannot combine with --deep or --thinking. |
--deep |
Agent-backed phases | Use the deep thinking profile. Cannot combine with --fast or --thinking. |
--max-fix-passes <n> |
auto, do, continue, revise-pr |
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. |
--restart |
continue |
Start over from the saved baseline, using the current issue and all comments. |
--force |
standalone phases, workspace removal | Re-run phase artifacts or allow removal of dirty managed workspaces. |
--yes |
supported mutation paths | Bypass supported dirty-tree preflights, 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. |
#Models and thinking profiles
All agent-backed phases default to openai-codex/gpt-6-astra. --model overrides the model across phases; --thinking applies one explicit level across phases.
| Phase | Fast | Default | Deep |
|---|---|---|---|
| Triage | low | medium | high |
| Writing and checking plans | low | high | xhigh |
| Implementation | low | medium | high |
| Code refinement | low | medium | high |
| Reviews A and B | medium | high | xhigh |
| Fixes | low | medium | high |
| Issue/PR publishing | low | low | low |
| Revision planning | low | high | xhigh |
| Revision implementation | low | medium | high |
| Revision review | low | high | xhigh |
| Revision fixes | low | medium | high |
max remains available through --thinking max. Astra has no non-reasoning mode: Pi clamps off to its minimal level, and sends both off and minimal selections to Astra as low effort.
#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. |
--max-fix-passes <n> |
Maximum shared budget for review and verification fix passes. Defaults to 3. |
--yes |
Continue past the dirty-tree 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