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>	(unset)	Opt in to a request-changes verdict at or above this severity. One of critical, high, medium, low (info is rejected). Without this flag the verdict is never request-changes — see Verdict. Ignored under --no-post.
--repo <owner/repo>	(git context)	Target repository. Overrides discovery from the current git remote; required when you are not inside the repo.
--no-post	false	Review the PR diff and print locally — write nothing to GitHub. See Read-only mode below.

Inherited globals that apply: --provider / --model / --lang, --no-cache, --allow-secrets, --verbose / --quiet. Under --no-post the local-render globals also apply (see below).

Read-only mode (--no-post)

commitbrief remote pr <ID> --no-post uses the PR diff purely as a review source and renders to your terminal exactly like a local review — it writes nothing back to GitHub (no inline comments, no verdict). Use it to triage a PR, pipe findings into another tool, or review with a CLI provider.

Because the output is local rather than GitHub, the flags that normal remote pr rejects all apply:

commitbrief remote pr 42 --no-post                     # cards in your terminal
commitbrief remote pr 42 --no-post --json | jq .
commitbrief remote pr 42 --no-post --output review.md
commitbrief remote pr 42 --no-post --cli gemini        # CLI provider, no API key
commitbrief remote pr 42 --no-post --fail-on=high      # exit-code gate

Aspect	Posting mode (default)	--no-post
GitHub writes	inline comments + verdict	none
Output	GitHub	terminal (--json/--markdown/--output/--copy/--compact)
Providers	API only	API or CLI (--cli)
--fail-on	ignored (verdict replaces it)	applies (exit code)
--request-changes-on	drives the verdict	ignored (noted)
Self-PR	blocked by GitHub	allowed (nothing is submitted)
Cache	not used	used (diff-hash, like local review)

--with-context is not combined with --no-post (it would read your local working tree, which need not match the PR's branch); it is noted-and-ignored if set. Still needs gh installed and authenticated — the diff is fetched through it.

Verdict

Severity order (high → low): critical, high, medium, low, info. A request-changes verdict is opt-in: it is only ever submitted when you pass --request-changes-on <sev> (flag below). Inline comments are posted regardless of the verdict.

Without --request-changes-on (default):

Situation	Verdict
No findings	approve
Only info findings	comments posted, then approve
Any non-info findings	comments posted, then comment

With --request-changes-on <flag>:

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

The notes below describe the posting mode. --no-post inverts most of them — see Read-only mode.

• API providers only. claude-cli / gemini-cli / codex-cli are refused at preflight — they emit prose, not the structured findings this command needs. See CLI tools. (Lifted under --no-post.)
• --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. (Applies under --no-post.)
• --json / --markdown / --output / --copy / --compact are rejected — the output channel is GitHub, not a local renderer. (All apply under --no-post.)
• Self-PR is blocked. GitHub does not allow you to review your own PR; CommitBrief rejects it before fetching the diff. (Allowed under --no-post — nothing is submitted.)
• 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.
• Standard review context lines. The same informational lines the local review prints surround the run: a header (commitbrief vX · provider: name/model · cache: …) above the tree, an analyzing N files · X added · Y removed status line inside it, and a footer (✓ Done in … · N findings · T tokens · $cost) below it. These are identical across every review command type.

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.
• CLI tools — why CLI providers (claude-cli / gemini-cli / codex-cli) are refused.
• Severity levels — what --request-changes-on ranks against.
• setup — configure the required API provider.