Remote pr command

Home / Commands / remote pr

Command: remote pr

Important

Targeted at v1.1.0. See [ADR-0016] in the planning docs for the design rationale.

commitbrief remote pr <PR-ID> reviews a GitHub pull request and writes the result back to GitHub: each finding is posted as an inline review comment, and the review is submitted with a verdict (approve / comment / request-changes). It drives your locally-installed gh CLI — CommitBrief makes no HTTPS calls of its own, so gh's auth, host resolution, and cross-fork handling are reused. This is a user-driven tool, not a hosted bot.

Usage

commitbrief remote pr 42                       # PR #42 in the current repo
commitbrief remote pr CommitBrief/web#10       # cross-repo (owner/repo#N)
commitbrief remote pr https://github.com/CommitBrief/web/pull/10
commitbrief remote pr 42 --request-changes-on=high
commitbrief remote pr 42 --repo CommitBrief/web

<PR-ID> accepts any form gh understands: a number, owner/repo#N, or a full URL.

Flags

Flag	Default	Effect
--request-changes-on <sev>	critical	Severity at or above which the verdict becomes request-changes instead of comment. One of critical, high, medium, low. info is rejected (you cannot request changes on an info-only review).
--repo <owner/repo>	(git context)	Target repository. Overrides discovery from the current git remote; required when you are not inside the repo.

Inherited globals that apply: --provider / --model / --lang, --no-cache, --allow-secrets, --verbose / --quiet.

Verdict

Severity order (high → low): critical, high, medium, low, info. With flag = --request-changes-on:

Situation	Verdict
No findings	approve
Only info findings	comments posted, then approve
Any finding at/above flag	comments posted, then request-changes
Findings exist but none reach flag	comments posted, then comment

Comment volume

When flag is critical or high: all critical/high findings are posted, and everything below is capped at 10 comments. When flag is medium or low: every finding at or above flag is posted, no cap.

How comments are placed

Each finding is anchored to the side of the diff its line actually lives on: RIGHT (the new file) for added and context lines, LEFT (the old file) for removed lines. CommitBrief builds this mapping from the parsed diff before posting, so a finding about deleted code lands on the deleted line instead of being rejected.

To keep the line numbers accurate, the diff handed to the model is prefixed with the line number each comment would attach to (<n>| in front of every changed line), so the model copies the number instead of counting it.

A finding whose line still falls outside the diff — or whose POST is rejected by GitHub — is not dropped. It is appended to the review-level summary under a "Findings that could not be attached to a specific line" heading, so you still see it. A N finding(s) could not be anchored… line is printed to stderr alongside the Posted X/Y comments summary.

Behavior notes

• API providers only. claude-cli / gemini-cli are refused at preflight — they emit prose, not the structured findings this command needs. See claude-cli / gemini-cli.
• --fail-on is ignored (with a warning). The GitHub verdict replaces the exit-code gate; the process exits 0 on a successful review submission and non-zero only on a real error.
• --json / --markdown / --output / --copy / --compact are rejected — the output channel is GitHub, not a local renderer.
• Self-PR is blocked. GitHub does not allow you to review your own PR; CommitBrief rejects it before fetching the diff.
• Pre-send guards run in warn-only mode. The secret scanner warns but does not abort (it's the PR author's code, not your local config).
• Race-safe. If the PR head moves while the review runs, CommitBrief retries once; if it moves again it aborts (PR too volatile) without submitting a review.
• Per-comment failures are tolerated. A comment that GitHub rejects is logged, counted, and the finding is moved to the review summary (see "How comments are placed"); the review verdict still submits, and a Posted X/Y comments, Z failed summary is printed.
• Posted text is English. Comment and verdict bodies are fixed English (PRs are read by mixed-locale teams); only local stderr progress/error lines are localized.
• Staged progress display. The pipeline stages (fetch → review → post → submit) render as the same animated tree the local review command uses on a TTY, and degrade to one line per stage transition in non-TTY/CI logs. --quiet suppresses it entirely.

Requirements

• The gh CLI on PATH, authenticated (gh auth login).
• An API provider configured (commitbrief setup).

See also

• diff — review a local range instead of a PR.
• claude-cli / gemini-cli — why CLI providers are refused.
• Severity levels — what --request-changes-on ranks against.
• setup — configure the required API provider.