Usage

#Choose a Workflow

#Manual Issue Run

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

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:

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:

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:

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:

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:

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 Reviews and Revisions

Use review-pr for a fresh, non-mutating review of an agent-authored open or draft PR. It inspects the complete pinned PR contribution, runs configured verification once, runs independent correctness and maintainability reviewers, and posts each review directly as its own PR comment. It never edits, commits, or pushes:

roark review-pr 456 --repo owner/repo

Use --no-comment to keep the complete review local. Verification runs only from --verify or trusted .roark/config.json configuration. On an unrestricted host, Roark may suggest an inferred package command but does not execute contributor-controlled PR code without that explicit authorization.

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

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.

These commands are intentionally separate. review-pr produces feedback; revise-pr consumes existing feedback and is the mutation-authorized step. Review never starts revision automatically.

#Workspace Commands

List managed workspaces:

roark workspace list

List and interactively select one or more workspaces to remove:

roark remove

Remove issue workspace 123 directly:

roark remove 123

Dirty workspaces require --force:

roark remove 123 --force

Use roark remove --pr 456 for a PR workspace.

Prune old clean workspaces:

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:

roark curate-issues 123 --repo owner/repo

Use create-issues to publish the approved plan:

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

See Issue curation.

#Following long-running work

Normal output is an operational view rather than a copy of generated Markdown: it identifies the target and current phase, keeps successful tool activity compact, reports phase wall time and verification status, then points to the complete artifact. Add --verbose to render completed agent responses and detailed tool statistics. Raw event, prompt, and tool-result debug output is not part of verbose mode.

Interactive terminals receive a target-first title that follows phase and outcome transitions. Use --no-title to opt out. Roark emits no title or ANSI sequences when output is redirected or piped, preserves complete redirected lines, and only shortens paths and lines for interactive terminal widths. Operational warnings remain on stderr.

#Common Options

See CLI reference for the full command and option reference.

#Next Steps

• Use Troubleshooting when a command stops unexpectedly.
• Use Operations runbook before scheduling.
• Use PR revisions for review feedback handling.