CLI reference
Commands, options, output and exit codes.
ocra review
Reviews code changes in the current Git repository.
ocra review [options]| Option | Meaning |
|---|---|
| (none) | Review uncommitted changes: staged, unstaged and untracked files |
--from <ref> | Review --to since it diverged from <ref> (merge base) |
--to <ref> | End of the range; defaults to HEAD; requires --from |
--commit <sha> | Review a single commit against its parent |
--format text|json | Output format; default text |
--output <file> | Write the result to a file instead of stdout |
--pr <number> | Review a GitHub pull request; see GitHub pull requests |
--repo <owner/name> | Repository of --pr (default: GITHUB_REPOSITORY or origin) |
--publish | With --pr: post the review to the pull request |
--full | With --pr: review every file, not only what changed since the previous review |
--max-cost-usd <n> | Spend limit for the run. Review tasks stop starting at 80% of it (tasks already running finish); verification and judging use the rest. If that runs out too, the remaining findings are reported not verified, so they cannot block, and the report says so |
--plan | Show selected and excluded files, bundles, review tasks and the size of each first prompt, without calling a model (free). Grouping by the light model is skipped, so a change set large enough to be grouped is shown one file per bundle |
--ultra | Favor recall over cost; see Modes |
--reviewers <ids> | Run only these reviewers, comma-separated (for example security) |
--no-repo-config | Ignore .ocra/config.json and the plugins it lists; models come from OCRA_MODEL_*. Use it on code you do not trust |
-h, --help | Show help |
--commit cannot be combined with --from or --to.
Progress
Progress goes to stderr, so --format json output on stdout stays machine-readable:
[ocra] Reviewing: Working tree changes
[ocra] 4 file(s) selected, 1 excluded · risk tier: lite
[ocra] 2 bundle(s) (grouped)
[ocra] 2 review task(s)
[ocra] correctness-1 started: auth session handling (2 file(s))
[ocra] correctness-1 reviewing with google/gemini-3.5-flash
[ocra] correctness-1 google/gemini-3.5-flash: 3 tool call(s), 19558 in / 118 out / 0 reasoning tokens, $0.0062
[ocra] correctness-1 completed in 5.9s · 0 finding(s)When a model is quiet for 30 seconds, ocra prints Model is thinking... so a long review never looks stuck.
Exit codes
| Code | Meaning |
|---|---|
0 | Review finished; verdict approved, approved_with_comments or minor_issues |
1 | Verdict significant_concerns: at least one critical finding the verifier confirmed. Unconfirmed critical findings give minor_issues and exit 0. The verdict is advice and can be influenced by the change under review; see How it works |
2 | Usage, Git or configuration error, or no review task completed |
3 | Review incomplete: some tasks failed, timed out or hit the spend limit (and the verdict is not blocking) |
130 | Interrupted with Ctrl-C or SIGTERM; the partial report is still printed and nothing is published |
JSON output
--format json prints the full report: the change request, risk tier, verdict and summary, coverage for every changed file (reviewed, failed, unreviewed, unchanged since the previous review, or excluded with a reason), for pull requests whether the run was incremental or full and why (scope), bundles, task outcomes, reviewer/bundle pairs the matrix skipped, findings verification dropped (refuted, with the reason), what the judge merged, dropped or recalibrated (judgement), findings with their resolved line ranges, token usage and cost, and warnings.
Sessions
Every run writes .ocra/sessions/<id>/events.jsonl (one event per line, appended as the run progresses) and report.json. The directory carries its own .gitignore, so logs are never committed and never show up as changes in the next review.
ocra --version
Prints the version.
ocra memory
Some findings are correct but accepted: the risk is handled elsewhere, or the team decided to live with it. Remember them so ocra stops reporting them:
ocra review # every finding shows an id, such as #1a2b3c4d
ocra memory add 1a2b3c4d --reason "Retries are capped by the gateway."
ocra memory listEntries go to .ocra/memory.json; commit the file to share them. A remembered finding (same reviewer, file and quoted code) is left out of the report and counted instead, and reviewers see the accepted findings for the files they review so they do not raise them again. For pull requests the file is read from the base commit, so a pull request cannot silence its own findings.