roark · docs
docs/usage.md

Usage

Day-to-day Roark commands and when to use each workflow.

Last updated

Edit on GitHubView Markdown

#Choose a Workflow

Goal Command
Scaffold repository config roark init
Run one issue locally roark do 123 --repo owner/repo
Preview eligible autorun issues roark auto --repo owner/repo --dry-run
Claim and run eligible issues roark auto --repo owner/repo --limit 1
Target one issue through autorun roark auto 123 --repo owner/repo
Continue a failed attempt roark continue 123 --repo owner/repo
Revise an existing PR roark revise-pr 456 --repo owner/repo
Inspect run status roark status 123 --repo owner/repo
Manage workspaces roark workspace list
Create follow-up issues from findings roark create-issues 123 --repo owner/repo --yes

#Manual Issue Run

Use do when you want the complete issue workflow without scheduler-style discovery.

bash
roark do 123 --repo owner/repo

This is the best first workflow for a new repository because it makes the target issue explicit.

#Autorun Discovery

Use auto without an issue when Roark should discover eligible issues by label:

bash
roark auto --repo owner/repo --limit 1

Keep --limit 1 unless you intentionally want multiple issues per process. Roark is one-shot, so repeated execution should be handled by cron, launchd, GitHub Actions, or another scheduler.

#Autorun Targeted Issue

Use auto <issue> when you want autorun behavior for one known issue:

bash
roark auto 123 --repo owner/repo

This bypasses discovery but still uses the autorun publishing and lifecycle path.

#Dry Run

Use --dry-run before scheduled runs or label changes:

bash
roark auto --repo owner/repo --limit 3 --dry-run

Dry run reports what would be selected. It does not claim issues, create branches, or run agents.

#Status

Use status to inspect persisted run state:

bash
roark status 123 --repo owner/repo
roark status --all --repo owner/repo

Status reads artifacts. It is useful when a scheduler has run Roark in the background.

#Continue

Use continue after readiness or verification fails:

bash
roark continue 123 --repo owner/repo --attempt 1

Continue should run from the same control checkout when possible. It depends on local artifacts and the persistent managed workspace.

#PR Revisions

Use revise-pr when a PR exists and you want Roark to respond to PR-scoped review feedback:

bash
roark revise-pr 456 --repo owner/repo

Roark classifies feedback, applies only must-fix-current items, verifies, pushes one revision commit, and posts one summary comment.

#Workspace Commands

List managed workspaces:

bash
roark workspace list

Remove one issue workspace:

bash
roark workspace remove --issue 123

Dirty workspaces require --force:

bash
roark workspace remove --issue 123 --force

Prune old clean workspaces:

bash
roark workspace prune --older-than 30d

Use Managed workspaces before deleting workspaces that may contain recoverable work.

#Issue Curation

Use curate-issues to turn reviewer findings into a deterministic issue creation plan:

bash
roark curate-issues 123 --repo owner/repo

Use create-issues to publish the approved plan:

bash
roark create-issues 123 --repo owner/repo --yes

See Issue curation.

#Common Options

Option Use
--repo owner/repo Select GitHub repository
--cwd path Use a specific control checkout
--out path Use a custom runs directory
--verify "cmd" Override verification command
--model provider/id Override Pi model
--thinking level Override thinking level
--attempt n Select an attempt
--force Regenerate phase artifacts
--yes Approve supported prompts or mutations

See CLI reference for the full command and option reference.

#Next Steps