coderabbit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CodeRabbit CLI and Configuration

CodeRabbit CLI 与配置

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.

本地优先的AI代码审查：在问题进入PR之前发现它们。 CodeRabbit CLI（

coderabbit

，别名

cr

）可在本地审查工作区或分支变更，让PR端审查变成确认环节而非迭代环节——这能节省可计费的PR审查次数（包括CodeRabbit自身的配额以及Copilot credits）。本文涵盖CLI的使用方法与

.coderabbit.yaml

的调优。PR端的机制（线程、重新请求、机器人循环）请查看

git-pr

技能文档。

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

审查本地变更 —— "审查我的变更"、"运行coderabbit"、提交前/推送前/PR创建前检查
执行审查-修复循环 —— 运行审查、修复有效的审查结果、重新运行以验证
配置CodeRabbit —— 创建或调整
```
.coderabbit.yaml
```
、减少审查干扰、禁用冗余的代码检查工具
查看限制信息 —— 各套餐的速率限制、审查预算
设置CLI —— 安装、认证、无头模式/CI环境使用

Critical Rules

关键规则

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.
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.
Use
--agent
output when driving fixes programmatically; the default plain-text mode is for humans.
Validate findings before fixing -- same rule as PR reviews: judge each finding on its merits; never blind-fix to silence the tool.
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.

审查会将代码上传至CodeRabbit服务。审查会将代码差异（及上下文）发送给CodeRabbit。对于包含敏感/未发布代码的仓库，在首次运行前请确认用户是否同意此操作。
审查会消耗每小时配额（免费版：每小时3次CLI审查）。请合理设定审查范围（使用
```
--committed
```
/
```
--uncommitted
```
、
```
--base
```
参数），并使用
```
coderabbit review findings
```
重放上次审查结果，无需消耗审查配额。
程序化修复时使用
--agent
输出；默认的纯文本模式面向人类用户。
修复前验证审查结果 —— 与PR审查规则相同：根据实际情况判断每个审查结果的合理性；切勿盲目修复以消除工具提示。
CodeRabbit为可选工具——请先查看代码审查政策（仓库的AGENTS.md/CLAUDE.md文件，若无则参考用户的全局代理指令；详见
```
git-pr
```
技能文档），确认首选的审查者与检查点。切勿在未获得项目政策或用户许可的情况下安装、认证或运行该工具。

Setup

安装设置

bash

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

, and

--self-hosted

;

auth org

switches the active organization.

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

bash

curl -fsSL https://cli.coderabbit.ai/install.sh | sh   # 或：brew install coderabbit
coderabbit auth login        # 浏览器OAuth认证；--agent参数会输出JSON以支持代理驱动的登录
coderabbit auth status       # 验证认证状态
coderabbit doctor            # 诊断运行时/认证/连接问题

auth login

还支持

--api-key <key>

（存储密钥而非使用OAuth）、

--region us|eu

和

--self-hosted

参数；

auth org

可切换当前活跃组织。

无需付费套餐：免费账户完成

coderabbit auth login

后，免费版即可使用CLI审查（每小时3次）——付费套餐增加了组织上下文、学习功能和更高的限制。无头模式/CI环境：使用

CODERABBIT_API_KEY

环境变量（需付费套餐的基于使用量的附加组件），或每次调用时使用

--api-key

参数。

coderabbit update

可自动更新CLI。

CLI必须在git仓库内运行。

cr

是

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.7): all tracked changes, base = repository default branch, plain-text output. v0.7 removed the older

--type <scope>

and

--plain

flags (

error: unknown option

) -- scope with

--committed

--uncommitted

, and plain is simply the default.

--light

runs a faster, lighter review policy for quick local iteration.

检查点	命令	审查内容
提交前	`coderabbit review --uncommitted`	已暂存+未暂存的已跟踪变更
推送前	`coderabbit review --committed`	本地仓库中未同步到基准分支的提交
PR创建前（全分支）	`coderabbit review --base main`	工作区+分支提交与基准分支的差异
仅子目录	`coderabbit review --dir packages/api`	指定路径下的变更
与特定提交对比	`coderabbit review --committed --base-commit {sha}`	自指定提交以来的变更
包含未跟踪文件	`coderabbit review --include-untracked`	还包含尚未添加到git的文件

默认设置（CLI v0.7）：所有已跟踪变更，基准分支为仓库默认分支，纯文本输出。v0.7版本移除了旧版的

--type <scope>

和

--plain

参数（会提示

error: unknown option

）——请使用

--committed

--uncommitted

指定范围，纯文本为默认输出模式。

--light

参数会运行更快、更轻量化的审查策略，适用于快速本地迭代。

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).
```
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.
```
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).

默认模式（无模式参数）—— 详细的纯文本反馈，包含修复建议，非交互式。
```
--agent
```
模式 —— JSON行格式：每行一个对象。审查结果对象包含
```
type: "finding"
```
、
```
severity
```
（
```
critical|major|minor|trivial|info
```
）、
```
fileName
```
、
```
suggestions
```
和
```
codegenInstructions
```
（为编码代理编写的指令——修复时请遵循这些指令）；当
```
codegenInstructions
```
为空时会出现
```
comment
```
字段。长时间审查过程中会出现心跳事件；最终的
```
complete
```
事件包含
```
status
```
（当审查范围无变更时，
```
status
```
为
```
"review_skipped"
```
且
```
findings: 0
```
）。
```
coderabbit review findings
```
—— 重放最近一次本地审查产生的缓存结果（无结果的会话会被跳过），无需重新分析，不消耗配额（
```
--dir <path>
```
会读取指定范围审查的缓存）。适用于修复迭代过程中；仅在最后阶段重新运行正式审查以验证修复效果。
```
coderabbit review --show-prompts
```
—— 打印最近一次本地审查使用的AI提示词，不会启动新的审查。
```
coderabbit stats
```
—— 查看审查统计信息（
```
--rebuild
```
参数会重新扫描审查历史）。

The Local Review-Fix Loop

本地审查-修复循环流程

Run

coderabbit review --committed --base {base} --agent

(or

--uncommitted

pre-commit; background it -- reviews take minutes).

Parse findings; triage by
```
severity
```
. Address
```
critical
```
and
```
major
```
first.
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.
Re-run the same review command to verify fixes. Stop when no valid
```
critical
```
/
```
major
```
findings remain, or the hourly bucket is exhausted (the CLI reports the limit -- wait or stop, never hammer).
Then push / create the PR; the PR-side review (if any) should 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

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

运行
```
coderabbit review --committed --base {base} --agent
```
（提交前使用
```
--uncommitted
```
；可后台运行——审查需要数分钟时间）。
解析审查结果；按
```
severity
```
优先级处理。优先解决
```
critical
```
和
```
major
```
级别的问题。
针对代码库验证每个审查结果（遵循代码规范、实际行为、项目文档）。根据
```
codegenInstructions
```
修复有效的问题；为无效问题添加一行说明供用户参考。
重新运行相同的审查命令以验证修复效果。当没有有效的
```
critical
```
/
```
major
```
级问题，或每小时配额耗尽时停止（CLI会提示限制信息——请等待配额重置，切勿频繁重试）。
然后推送代码/创建PR；PR端的审查（若有）应返回无问题或基本无问题的结果。

提交修复时应描述变更内容，而非触发修复的原因——例如提交信息应为

fix: validate empty page cursor

，而非

fix: coderabbit fixes

或

fix: review round 2

（详见

git-commit

技能文档）。修复时不得添加重复代码含义的注释。

正常流程为两次循环（审查、修复、验证）。若超过三次循环，说明审查结果被视为干扰——请重新评估结果的有效性或调整配置（详见

references/configuration.md

）。

Rate Limits (Per Developer, Per Hour)

速率限制（每位开发者每小时）

Plan	CLI reviews	PR reviews	Files/review
Free	3	1 (summary only)	150
Pro	5	5	300
Pro+	10	10	300
Enterprise	12	12	300

The Lite plan was retired (June 2026); Free / Pro / Pro+ / Enterprise are current. Beyond the hourly allowance, the usage-based add-on bills $0.25 per reviewed file (Pro and up). Open-source public repos get free reviews with popularity-based limits.

套餐	CLI审查次数	PR审查次数	每次审查文件数
免费版	3	1（仅摘要）	150
Pro版	5	5	300
Pro+版	10	10	300
企业版	12	12	300

Lite套餐已停用（2026年6月）；当前可用套餐为免费版/Pro版/Pro+版/企业版。超出每小时限额后，基于使用量的附加组件将按每份审查文件0.25美元计费（Pro版及以上）。开源公共仓库可免费获得审查服务，限额基于仓库热度。

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) before committing.

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).

仓库根目录下的

.coderabbit.yaml

文件同时管控PR端和CLI端的审查（CLI还支持通过

-c <file>

参数加载额外的指令文件，例如

CLAUDE.md

）。对于类型化、已配置代码检查的项目，目标是仅获取高价值的审查结果：设置

profile

、

tone_instructions

，禁用与CI重复的代码检查工具，为生成文件设置

path_filters

。提交配置修改前，请使用

coderabbit config validate [file]

（对照官方最新 schema 检查）验证编辑内容。

参考文档：完整的schema要点、配置优先级、适用于类型化/已配置代码检查项目的低干扰模板，以及PR端命令（
@coderabbitai review
vs
full review
、暂停/恢复、配置导出）请查看
references/configuration.md
。

Key Gotchas

常见陷阱

--committed
needs commits,
--uncommitted
needs a dirty tree -- reviewing the wrong scope silently reviews nothing (
```
review_skipped
```
); match the scope to the checkpoint.
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.
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.
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.
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.
--agent
emits JSON lines, not a JSON document -- parse line-by-line; do not
```
JSON.parse
```
the whole output.
--type <scope>
and
--plain
no longer exist (removed in v0.7;
```
error: unknown option
```
) -- older docs and allowlists reference them; use
```
--committed
```
/
```
--uncommitted
```
and rely on the plain default.

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
)

--committed
需要已提交的变更，
--uncommitted
需要未提交的工作区变更 —— 若审查范围错误，会静默地不执行任何审查（
```
review_skipped
```
）；请确保审查范围与检查点匹配。
coderabbit review findings
仅重放结果，不重新审查 —— 修复后，缓存结果仍会显示之前的问题；只有重新运行正式审查才能验证修复效果。该命令还会跳过无结果的会话：即使完成了无问题的验证运行，它仍会重放旧的审查结果，这不属于回归问题。
配额按小时计算，而非按天 —— 出现"限额已达"提示意味着需等待配额重置窗口，而非当天停止使用。请合理安排验证运行时间，确保最终的验证环节能在配额内完成。
CLI审查与PR审查使用独立的配额池 —— 在本地消耗CLI审查配额不会减少PR端的可用次数，这正是本地优先流程的意义所在。
组织上下文需要匹配访问权限 —— 对于未关联到你的CodeRabbit组织的仓库，审查将以受限的免费模式运行（无学习功能/组织上下文）；结果会与同一代码的PR端审查结果不同。
--agent
模式输出JSON行，而非JSON文档 —— 请逐行解析；不要对整个输出执行
```
JSON.parse
```
。
--type <scope>
和
--plain
参数已不存在（v0.7版本移除；会提示
```
error: unknown option
```
）—— 旧文档和允许列表中可能会提到这些参数；请使用
```
--committed
```
/
```
--uncommitted
```
指定范围，并依赖默认的纯文本输出。

参考文档：
.coderabbit.yaml
调优与PR命令请查看
references/configuration.md
参考文档：自动批准模式请查看
references/allowlist.md
参考文档：PR端审查循环、线程处理：
git-pr
技能（
references/bot-review-loop.md
）