birch review

birch review run <pr-id> runs the same AI reviewer the app uses for auto-review and prints where the markdown report landed. It is one of Birch’s Anthropic API features.

Note

On-demand review is currently available via the birch CLI only; a UI entry point is planned.

Synopsis

terminal

birch review run <pr-id>

<pr-id> is the PR’s external id (e.g. 1234). Unlike the pr subcommands, a URL is not accepted here. The PR must already be known to Birch; an unknown or ambiguous id exits 1.

Requirements

The review calls the Anthropic API, so the process that runs it needs the ANTHROPIC_API_KEY environment variable:

• App running — the command relays to the app, which runs the review; the key must be in the app’s environment.
• App not running — the CLI runs the review itself; the key must be in your shell’s environment.

Without the key the review fails with AI provider is not configured. Set ANTHROPIC_API_KEY. The model is a Claude Sonnet model chosen by the app; it is not configurable.

Output

Text output is the final status followed by the report path (or the error message):

text

Completed  /Users/you/Library/Application Support/birch/artifacts/review/<job-id>/report.md

--json output:

json

{
  "jobId": "0b6f2c1e-…",
  "status": "Completed",
  "reportPath": "…/artifacts/review/<job-id>/report.md",
  "attempts": 1,
  "chunks": 1
}

An error field appears (and reportPath is omitted) when the review failed. attempts and chunks are counters from the review job — how many model attempts it took and how many diff chunks were processed.

Exit codes

Code	Meaning
0	The review completed and the report was written.
1	The PR could not be resolved (not found / ambiguous).
2	Invalid operation or any other error (e.g. an app-relay failure or an unexpected exception).
3	The review ran but didn’t complete — including “AI provider is not configured”. Distinct from usage errors so scripts can tell “bad invocation” from “review failed”.
130	Cancelled.

Reports

Reports are markdown files under artifacts/review/<job-id>/report.md in Birch’s data folder (see Storage & data). Inside the app, a completed review opens in the review-report window — see AI code review; from a terminal, the printed path is a plain markdown file you can open with anything.

Relation to auto-review

Settings → AI → Automatically review new PRs (off by default) runs this same reviewer on newly synced PRs in the background; birch review run is the on-demand trigger for one specific PR — including re-reviewing a PR after it changed.

Warning

A review is long-running (it calls a remote API, possibly several times for a large diff) and spends your API credit. In CI-like scripting, budget for runtimes of minutes, check the exit code — 3 means the review itself failed — and avoid triggering it in a tight loop.