coderabbit

CodeRabbit CLI and Configuration

Local-first AI code review: catch issues before they reach the PR. The CodeRabbit CLI (coderabbit, alias cr) reviews working-tree or branch changes locally, so the PR-side review becomes confirmation instead of iteration -- this saves billable PR review rounds (both CodeRabbit's own quota and any Copilot credits). Covers the CLI surface and .coderabbit.yaml tuning. PR-side mechanics (threads, re-requests, the bot loop) live in the git-pr skill.

Verified against CodeRabbit CLI v0.8.2 (2026-09-29): every subcommand's --help on the official build, plus the CLI changelog. Flags are tagged with the version that introduced them. If coderabbit --version reports something newer, diff --help of each subcommand against this list and read the changelog entries since v0.8.2 before relying on flag details here.

When to Use

• Reviewing local changes -- "review my changes", "run coderabbit", pre-commit/pre-push/pre-PR checks
• Driving a review-fix loop -- run review, fix valid findings, re-run to verify
• Configuring CodeRabbit -- create or tune .coderabbit.yaml, reduce review noise, disable redundant linters
• Checking limits -- rate limits per plan, review budgeting
• Setting up the CLI -- install, auth, headless/CI usage

Critical Rules

1. Reviews upload code to CodeRabbit's service. A review sends the diff (and context) to CodeRabbit. On a repo with sensitive/unpublished code, confirm the user is OK with that before the first run.
2. Reviews consume a per-hour quota (Free: 3/hour CLI reviews). Scope deliberately (--committed/--uncommitted, --base) and use coderabbit review findings to replay the last result without spending a review.
3. Use --agent output when driving fixes programmatically; the default plain-text mode is for humans. There is no --plain flag (and no --type): both were removed in v0.7 and fail with error: unknown option plus the usage text. v0.8 exits 1 on it; v0.7 exited 0, so on an older binary a piped or tailed run looks clean while nothing was reviewed. Do not guess flags; coderabbit review --help on the installed binary is the whole surface.
4. Validate findings before fixing -- same rule as PR reviews: judge each finding on its merits; never blind-fix to silence the tool.
5. CodeRabbit is optional -- check the Code Review Policy first (repo AGENTS.md/CLAUDE.md, falling back to the user's global agent instructions; see git-pr skill) for the preferred reviewer and checkpoints. Never install, authenticate, or run it on a project whose policy or user hasn't opted in.

---

Setup

curl -fsSL https://cli.coderabbit.ai/install.sh | sh   # or: brew install coderabbit
coderabbit auth login        # browser OAuth; --agent emits JSON for agent-driven login
coderabbit auth status       # verify
coderabbit doctor            # diagnose runtime/auth/connectivity issues

auth login also accepts --api-key <key> (store a key instead of OAuth), --region us|eu, --self-hosted, and --no-browser (print the URL for a browser that can reach the localhost callback); auth org switches the active organization. Every auth subcommand takes --agent for JSON output.

No paid plan required: the Free plan includes CLI reviews (3/hour) after coderabbit auth login with a free account -- paid plans add org context, learnings, and higher limits. Headless/CI: CODERABBIT_API_KEY env var with an Agentic API key (requires the usage-based add-on on paid plans), or --api-key per call. coderabbit update self-updates.

The CLI must run inside a git repository. cr is a shorthand alias for coderabbit.

Review Scopes and Checkpoints

Checkpoint	Command	Reviews
Before commit	coderabbit review --uncommitted	Staged + unstaged tracked changes
Before push	coderabbit review --committed	Local commits not in the base branch
Before PR (full branch)	coderabbit review --base main	Working tree + branch commits vs base
Subdirectory only	coderabbit review --dir packages/api	Changes under a path
Vs specific commit	coderabbit review --committed --base-commit {sha}	Changes since a commit
Include untracked files	coderabbit review --include-untracked	Also files not yet added to git

Defaults (CLI v0.8): all tracked changes, base = repository default branch, plain-text output, the local review policy. v0.7 removed the older --type <scope> and --plain flags (error: unknown option) -- scope with --committed/--uncommitted, and plain is simply the default.

Local reviews keep a checkpoint (v0.7.7+). Each review saves context for its scope -- review directory, branch, and base -- that later runs in the same scope reuse; a --dir src run and a whole-repository run keep separate checkpoints, changing the base resets it, and a failed review keeps the last successful one. The docs call this incremental, but it does not narrow what gets reported: observed on this repo (2026-09-30), a second --committed --base main run on the same branch reported six findings in commits the first run had passed with zero. Treat every run as a review of the whole scope, and a clean pass as one sample, not proof. --fresh (v0.8.2) discards the checkpoint and reviews the scope without the saved context.

Review depth (v0.8): --deep runs the full pull request review policy locally -- the closest the CLI gets to what the PR-side review will say. Use it for the final pre-PR pass on repos where the CLI is the only lane (no PR-side auto-review); keep the default policy for the iterate-and-fix loop. Its quota cost is undocumented, so compare coderabbit usage before and after the first one. --deep "<focus>" (focus text) is early access only. --light is gone from --help but still accepted as a legacy alias for the default review -- it no longer makes anything lighter, so drop it from scripts. --deep needs a compatible server; if it is refused, report that the CLI needs updating rather than falling back to a default review silently.

Other review options:

• --use-credits -- consent to bill this review as usage-based when it exceeds the included allowance (the add-on's On demand mode asks for it). It spends money: never pass it without the user's explicit approval for that run.
• --remote owner/repo --base main --source-branch <ref> (v0.7.7) -- review a GitHub repository server-side without a local checkout; the repo must be installed in the active org, under 300 changed files.
• -c, --config <files...> -- extra instruction files (e.g. CLAUDE.md) for one run.
• --api-key <key> --region us|eu -- authenticate one run without storing the key (headless/CI; see the allowlist Caveat).

Output Modes

• Default (no mode flag) -- detailed plain-text feedback with fix suggestions, non-interactive.
• --agent -- JSON-lines: one object per line. Finding objects carry type: "finding", severity (critical|major|minor|trivial|info), fileName, suggestions, and codegenInstructions (written for coding agents -- follow them when fixing); a comment field appears when codegenInstructions is empty. Heartbeat events appear during long reviews; a final complete event carries status ("review_skipped" with findings: 0 when the scope has no changes). A depleted bucket ends the run at exit code 1 with {"type":"error","errorType":"rate_limit","recoverable":true,"metadata":{"waitTime":"7 minutes"}} and no findings -- the exit status alone cannot tell a bounce from a real failure, so branch on errorType, take the retry window from metadata.waitTime (wait it out plus a minute, then re-run), and never read the empty result as a clean review. Since v0.7.7 any failed or incomplete review exits 1. Security findings add category, CWE, reachability and exploitability; unverified findings are listed and counted separately and carry no fix prompt (inspect them, don't auto-fix them); a review billed as usage-based adds usageCost.
• coderabbit review findings -- replay cached findings from the most recent local review that produced findings (clean sessions are skipped), with no new analysis and no quota cost (--dir <path> reads a scoped review's cache). Use between fix iterations; only re-run a real review to verify at the end. --clear (v0.7.7) dismisses the stored findings for the current scope (directory + branch + base) once they are fixed or rejected, so later replays stop surfacing them.
• coderabbit review --show-prompts -- print the AI prompts from the most recent local review, no new review.
• coderabbit stats -- review statistics (--rebuild rescans review history).
• coderabbit usage (--agent for one JSON event; coderabbit --usage and coderabbit review --usage are aliases) -- since v0.8, the included-review allowance for the current repository: remaining vs limit over a rolling 1-hour window (includedReviews.remaining, .limit, .rollingWindowMs, and .fullCapacityInMs, the time until the bucket is full again). It also reports the billing period (billingPeriod): organization, whether usage billing (overage) is active (usageBillingStatus), your review count, the usage-based spend so far (spendCents), and the period reset date. Each block carries a state (available when the server answered). Read it before a local loop: it spends no review. The output does not name the lane, so it does not replace @coderabbitai rate limit (below) for a PR-side retry window. The installed binary is the source of truth, not the docs page -- the online reference still calls this billing-only; verify with --help.
• coderabbit pullrequest <number|url> -- reads CodeRabbit's existing output on a GitHub PR: no review is run and none is spent. --show-threads --agent returns the inline thread roots as JSON (thread and comment IDs, path/line, isResolved, isOutdated, head commit). --show-prompts returns one consolidated fix prompt that also carries an Outside diff comments: section, which a thread-only pass never sees. It needs github.com and a repo installed in the active org, and it resolves a bare number from the local origin. Thread handling and resolution stay in the git-pr skill.
• @coderabbitai rate limit -- not a CLI command: a PR comment, and the only on-demand read of the PR-side bucket. Reports the remaining allowance and when the next review becomes available, and does not consume a review (aliases rate-limit, limits, quota). Answers within seconds, even while rate-limited: "Your next review will be available in N minutes" -- the only durable read of that window, since the notice edited into the summary comment can vanish. Post it before opening a loop, and after a bounce instead of probing with triggers. It spends no review, but it is still a PR comment -- a write, subject to the usual approval.

The Local Review-Fix Loop

1. Run coderabbit review --committed --base {base} --agent (or --uncommitted pre-commit; background it -- reviews take minutes).
2. Parse findings; triage by severity. Address critical and major first.
3. Validate each finding against the codebase (conventions, actual behavior, project docs). Fix valid ones per codegenInstructions; note invalid ones with a one-line rationale for the user.
4. Re-run the same review command to verify fixes -- it reviews the whole scope again, so new findings on untouched code are normal, not a regression. Stop when no valid critical/major findings remain, or the hourly bucket is exhausted (coderabbit usage shows what remains; a bounce reports the wait -- wait or stop, never hammer).
5. Then push / create the PR -- once the change is completely finished, not once the findings are fixed. Where PR-side auto-review and auto_incremental_review are on (both default), the push is the review request and it reviews whatever the branch holds at that moment: remaining tasks, tests, docs and config belong in the same push, or each leftover costs another PR-side window. The PR-side review (if any) should then come back clean or near-clean.

Commit fixes by what they change, never by what prompted them -- fix: validate empty page cursor, not fix: coderabbit fixes or fix: review round 2 (see the git-commit skill). Fixes must not add code comments that restate what the code already reads.

Two passes (review, fix, verify) is the normal shape. More than three passes means findings are being treated as noise -- re-evaluate validity or tune config (see references/configuration.md).

Rate Limits (Per Developer, Per Hour)

Plan	CLI reviews	PR reviews	Chats	Files/review
Free	3	1 (summary only)	--	150
OSS (public repos)	3	1--10, by repo popularity	25	100--300, by popularity
Essentials (was Pro)	5	5	50	150
Team (was Pro+)	8	8	75	300
Advanced	10	10	100	300
Enterprise	12	12	100	300

Plans were renamed in September 2026: Essentials was Pro, Team was Pro+, and Advanced is new. The run-configuration block prints the new name. Grandfathered Pro+ subscriptions keep 10 reviews/hour even though they now display as Team, and old Pro/Pro+ subscriptions keep their old throttling ladders. Beyond the hourly allowance, the usage-based add-on bills per reviewed file ($0.25/file, as quoted in the rate-limit notice). Chats are a separate allowance: a reply in a CodeRabbit review thread gets a chat answer, which is not a review and does not draw from the PR review bucket (git-pr skill, references/bot-review-loop.md, Fixes Confirmed in the Thread).

The table is a CEILING, not the rate you get -- fair-usage throttling sets the effective PR-side allowance below it. The refill rate comes from the developer's recent PR review count over a rolling window of either the past 24 hours or the past 7 days; the plan allowance itself is not changed. Documented ladders by reviews in the last 7 days:

Plan	Full rate	Steps down to	1/hr, one at a time
Essentials	0--29 -> 5/hr	30--39 -> 4, 40--49 -> 3, 50--59 -> 2	60+
Team	0--39 -> 8/hr	40--49 -> 6, 50--59 -> 4, 60--69 -> 2	70+
Advanced	0--49 -> 10/hr	50--59 -> 8, 60--69 -> 4, 70--79 -> 2	80+

Enterprise stays at 12/hr unless the contract enrolls in adaptive limits. Observed live on the old Pro plan, crossing a tier mid-loop: 4/hr at round 1, 3/hr two rounds later, then a bounce. On Team, 23 attempts in 7 days still gave the full 8/hr.

Two consequences. A heavy review week throttles the next one -- the binding window is days, not the hour, and capacity trickles back as old reviews age out instead of resetting on the hour. And a bounce is free but pointless: "a blocked push does not consume a review or delay when your next review becomes available", since capacity is set by earlier completed reviews -- yet a refused round is never queued, so extra triggers inside a closed window buy nothing. Probe with @coderabbitai rate limit (no review consumed) rather than with triggers -- verified live: after two bounces it still quoted a window closing 54 minutes after the last completed review, so the bounces moved nothing. (The run-configuration footer says "review attempts over the past 7 days", but the documented ladders count reviews; treat the footer's number, not its noun, as the fact.)

Past the included limit, the usage-based add-on decides what happens, and its admin-set mode decides which: Automatic keeps reviewing and bills the overage, On demand pauses until a seat-holder authorizes each review, Off stops until the included allowance resets. Only Automatic is a release valve -- and fair-usage spacing is a separate mechanism layered on top.

Which plan row applies is something you must be told -- but the LIVE allowance is readable in two places: the "Run configuration" block inside each posted review names the plan and the current reviews-per-hour figure (read it off the most recent review before planning a loop), and @coderabbitai rate limit reports the remaining allowance plus next availability on demand, without spending one. The rest is silent about the plan: coderabbit usage reports a repository's included allowance and the billing period, but not the tier, and the PR-side API never mentions one. Declare it in the Code Review Policy (git-pr skill) -- CodeRabbit plan: team until 2026-10-20, then essentials -- in the repo's AGENTS.md/CLAUDE.md, or globally for every repo. It decides real behaviour: how many PRs can be non-draft at once, how many rounds to budget, and how much iteration belongs in the CLI lane instead. Re-plan when a trial lapses; a queue tuned for 10 reviews/hour stalls at 5. Undeclared, take the floor from observed behaviour (bot_bucket) rather than assuming the best case.

Where a Bounce Shows Up

A depleted bucket passes for a clean result in every lane that ignores the lane's own signal. Each lane does report it -- but never as a failed run, and never in the field most checks look at. Know the tell for the lane you are in:

Lane	What a bounce looks like	The tell
CLI (--agent)	Exit 1 with zero findings -- identical to a failure by exit status, and "no findings" reads as clean	{"type":"error","errorType":"rate_limit",...,"metadata":{"waitTime":"7 minutes"}} -- branch on errorType, never on the findings count
CLI (default output)	The run ends with a limit message and no findings	Read the message; do not treat the empty result as a passing review
PR-side	Often nothing at all -- no review, no threads, no comment -- plus a green CodeRabbit check in the PR's checks list	That check's description reads Review rate limited (state is SUCCESS for every finished outcome): gh pr checks --json name,state,description. Review completed is the reviewed case, and Review in progress (state PENDING) means it is still running -- wait rather than trigger

The PR-side row is the one that misleads most: the checks list shows a tick next to CodeRabbit between passing CI jobs, so the PR reads as reviewed-and-green when the code was never looked at. PR-side handling (windows, re-triggers, the loop) lives in the git-pr skill.

Only the PR itself can tell you when a PR-side round may retry -- ask it with @coderabbitai rate limit. Three dead ends around it, so no one spends the time again:

Where you might look	What you actually get
coderabbit usage	The repository's included allowance (remaining, rolling 1-hour window, time to full) plus the billing period. It does not name the lane and gives no PR-side retry window
CI logs behind the check	Nothing: CodeRabbit posts a commit status, not an Actions run (check-runs is empty, target_url is null). Log-diagnosable hard limits are a Copilot thing
The quota notice on the PR	A per-PR estimate that the next summary-comment edit can delete -- two PRs of one developer quoted 48 and 10 minutes 104 seconds apart, while a third PR's review completed 8 minutes later

What does answer it: a @coderabbitai rate limit comment (remaining allowance + next availability, no review consumed), and the newest Review completed across all your open PRs, since the bucket is per developer (bot_bucket in git-pr's references/bot-review-loop.md). If a sibling PR was reviewed after your bounce, the bucket is open now.

Configuration

.coderabbit.yaml at the repo root governs both PR-side and CLI reviews (the CLI also accepts -c <file> for extra instruction files, e.g. CLAUDE.md). For typed, well-linted projects the goal is high-level findings only: profile, tone_instructions, disabled CI-redundant linters, path_filters for generated files. Validate edits with coderabbit config validate [file] (checks against the current official schema, CI-friendly exit codes) before committing. Since v0.7.7 coderabbit config also generates and applies a config (--agent --generate --profile chill for a proposal) and the CLI discovers .coderabbit.config.ts when no YAML exists.

Reference: See references/configuration.md for the full schema highlights, config precedence, the low-noise template for typed/linted projects, and PR-side commands (@coderabbitai review vs full review, pause/resume, config dump).

Key Gotchas

1. --committed needs commits, --uncommitted needs a dirty tree -- reviewing the wrong scope silently reviews nothing (review_skipped); match the scope to the checkpoint.
2. coderabbit review findings replays, it does not re-review -- after fixing, cached findings still show; only a fresh review verifies fixes. It also skips clean sessions: even after a clean verify run, it replays the older findings, which is not a regression.
3. The quota is per-hour, not per-day -- a "limit reached" message means wait for the window, not stop for the day. Plan verify runs so the final pass fits the bucket. In --agent mode the bounce is a rate_limit error line at exit 1 -- indistinguishable from a real failure by exit status alone, and a findings-count check reads it as clean. Branch on errorType and take the window from metadata.waitTime.
4. CLI reviews and PR reviews draw from separate buckets -- burning CLI reviews locally does not reduce the PR-side allowance, which is the point of the local-first flow.
5. Org context needs matching access -- on a repo not linked to your CodeRabbit org, reviews run in limited free mode (no learnings/org context); results differ from PR-side reviews on the same code.
6. --agent emits JSON lines, not a JSON document -- parse line-by-line; do not JSON.parse the whole output.
7. --type <scope> and --plain no longer exist (removed in v0.7; error: unknown option, exit 1 since v0.8) -- older docs and allowlists reference them; use --committed/--uncommitted and rely on the plain default. --light still parses but is only an alias for the default review since v0.8; --deep is the real depth switch.
8. A PR-side rate limit is silent and green -- no review, no threads, usually no comment, and a passing CodeRabbit check whose description reads Review rate limited. Nothing about the PR looks wrong, so an unreviewed PR gets reported as reviewed. Read that description before concluding anything from a quiet PR-side round (Where a Bounce Shows Up).
9. A quoted retry window is an estimate, and it is not durable -- it is edited into the summary comment and a later edit can remove it, while different PRs quote wildly different numbers at the same moment. Capture it when you see it, take the smallest one visible across your PRs, and treat a sibling PR's Review completed as the real all-clear (Where a Bounce Shows Up). Don't wait out the largest number you can find.
10. The push is the PR-side review request -- with auto-review plus auto_incremental_review, every push spends a PR-side review of whatever is on the branch, from a bucket that is per developer, not per PR. Finish the whole change locally, then push once; the local lane (separate bucket) is where iteration belongs.
11. A rate-limited attempt can leave its commits looking reviewed -- once the window reopens, a plain @coderabbitai review over unchanged commits answers "does not re-review already reviewed commits" and the round silently never happens, so the recovery trigger after a bounce is @coderabbitai full review. It does not always stick, though: observed on this repo, the next push after a bounce resumed its incremental range from the last completed review and did re-cover the two skipped commits unprompted. Read the review's own "Commits" block to see which range it actually took, rather than assuming either way. The same forcing form is the fix for a wedged "Review queued" (observed stuck 2+ hours): nudge after ~1 hour instead of waiting it out.
12. A clean local pass is one sample, not proof -- runs vary: observed here, a second run on an unchanged scope reported six findings in code the first run had passed clean. Budget for that, and let the PR-side round have the final say where it exists. --fresh (v0.8.2) reviews without the saved checkpoint context.
13. The cloud commands moved under code in v0.8.1 -- coderabbit code handoff (the top-level handoff from v0.8.0 is now a hidden alias) and coderabbit code skills import. Both upload local material to CodeRabbit Cloud: approve each run (references/allowlist.md).

Reference: See references/configuration.md for .coderabbit.yaml tuning and PR commands Reference: See references/allowlist.md for auto-approval patterns Reference: PR-side review loops, thread handling: git-pr skill (references/bot-review-loop.md)