CodeRabbit Documentation - AI code reviews on pull requests, IDE, and CLI

Commands

cr is the short alias for coderabbit. Both work identically — use whichever fits your workflow.

Command	Description
`cr`	Run code review in non-interactive plain text mode (default)
`cr --agent`	Output structured JSON for agent-driven workflows
`cr review --light`	Request a lighter CLI review for active local development
`cr auth`	Authentication commands
`cr auth login`	Authenticate via browser OAuth, self-hosted (`--self-hosted`), or API key (`--api-key "<key>"`); select CodeRabbit US or EU with `--region`
`cr auth logout`	Log out from CodeRabbit
`cr auth status`	Show current authentication status
`cr auth org`	Choose or switch the login/default organization for browser-based auth
`cr config validate [file]`	Validate CodeRabbit YAML syntax and settings against the current official schema
`cr stats`	Show review statistics
`cr doctor`	Check the CLI installation, local storage, authentication, Git repository state, update policy, and service connectivity
`cr review`	AI-driven code reviews with plain text or agent output
`cr review findings [--dir <path>]`	Show findings from the most recent local review with findings for the selected review context
`cr skills`	Install or update verified CodeRabbit skills for supported coding agents
`cr usage`	Show billing-period review usage and spend when available
`cr session import --task-id TASK_ID`	Download a cloud coding session summary for a local agent
`cr session export [options]`	Upload a local coding session summary or create a cloud coding task
`cr feedback "<message>"`	Send feedback about a review when the command is enabled for your account
`cr update`	Check for and install the latest CLI version

Review modes

Mode	Description
Default (no flag required)	Detailed plain text feedback in the terminal
`--agent`	Structured JSON output for coding agents and automation
`--light`	Faster local review policy for feedback on active development work

Review scope

cr review reviews tracked changes by default: committed changes, staged changes (including new files added with git add), and unstaged edits to tracked files.

Command	Files reviewed
`cr review`	Tracked changes
`cr review --committed`	Only committed changes
`cr review --uncommitted`	Staged changes and unstaged edits to tracked files
`cr review --include-untracked`	Tracked changes plus non-ignored files not added to Git

New files are included once staged with git add. To review them before staging, use --include-untracked. You can combine it with --uncommitted, but not with --committed. Contradictory scope flags, such as --committed with --uncommitted, are rejected before a review starts.

`--agent` review output

cr review --agent writes one JSON object per line to stdout. Read the stream line by line and handle events by their type. Finding events use these fields:

Field	Description
`type`	Always `finding` for review results
`severity`	One of: `critical`, `major`, `minor`, `trivial`, `info`, `none`
`fileName`	File path for the finding
`codegenInstructions`	Agent-oriented fix instructions
`suggestions`	Suggested fix commands or snippets
`comment`	Human-readable review comment, included when `codegenInstructions` is empty

Other event types in the stream include review_context, status, heartbeat, complete, and error. heartbeat events are periodic keep-alive signals — reset timeout timers on receipt and otherwise ignore them. For finding events, use codegenInstructions for agent fix logic and fall back to comment when it is absent. When the selected review scope is skipped because it contains too many files, the review fails with an error event. The event can include these optional, additive fields:

Field	Description
`candidates`	Mutually exclusive narrower-scope suggestions computed from the submitted files. Suggestions can use `--committed`, `--uncommitted`, or up to five `--dir` scopes, and include an estimated local file count and a fit indicator relative to the server-reported limit. The estimate is intentionally conservative, so a candidate marked over the limit may still fit after server-side filtering.
`candidatesNote`	Guidance that accompanies the narrower-scope suggestions.

These fields do not change the existing error contract, so integrations do not need to handle them. Candidates are alternatives, not an automatic partition of the full change set. The CLI does not select a candidate or retry the review. The user or agent must choose one suggestion and rerun the narrower command manually. In plain mode, the same failure can print a Narrower scopes found in this diff block with concrete commands, estimated file counts, and fit indicators. The CLI does not increase the limit, split the review, or retry automatically; choose one command and rerun it manually. When the selected review scope has no file changes, cr review --agent still emits the review_context event, then emits a status event with status: "review_skipped" and a complete event with status: "review_skipped", findings: 0, and message: "No changes detected". Plain mode prints a no-changes message and exits without starting a review.

Diagnostics

Run cr doctor when installation, authentication, or review startup fails. The command checks:

CLI runtime and version
Local CodeRabbit storage directory
Authentication state and auth environment
Current Git repository and branch metadata
Auto-update policy
CodeRabbit backend reachability
CodeRabbit WebSocket reachability

cr doctor exits with status code 1 when any check fails. Warnings are shown in the report, but they do not cause a non-zero exit code.

Configuration validation

Use cr config validate to check a CodeRabbit YAML file before committing or deploying it.

# Validate .coderabbit.yaml or .coderabbit.yml at the repository root
cr config validate

# Validate a specific file
cr config validate path/to/config.yaml

Without a file argument, the command finds the Git repository root and checks .coderabbit.yaml, then .coderabbit.yml. With a file argument, it validates that path instead. The command checks YAML syntax first, then fetches the current official schema and validates the parsed configuration. Errors identify the affected line, configuration path, and expected value when available.

Exit code	Meaning
`0`	The file is valid against the current schema
`1`	The file is missing or unreadable, contains invalid YAML or settings, or the current schema could not be loaded or used

For browser-based validation, use the interactive YAML validator.

Skills command

Run cr skills in an interactive terminal to install or update CodeRabbit skills for detected Codex, Claude Code, Cursor, Gemini CLI, and GitHub Copilot setups. The command verifies the latest published skills release, previews every planned path and change, and asks once for confirmation with No selected by default.

cr skills

The command has no installation flags or subcommands. Non-interactive invocations do not install or update skill files, although they can clean stale CLI ownership records. After confirmation, the command can replace locally modified CLI-managed copies and refresh verified global package-runner or Cursor plugin installs. It leaves unsafe or ambiguous conflicts and project-level copies unchanged, and it protects official Codex and Claude Code plugin files for their marketplaces to update. See CodeRabbit Skills for installation and ownership details.

Stats command

Command	Description
`cr stats`	Show stats (builds on first run)
`cr stats --rebuild`	Rescan review history and rebuild stats

Usage command

Run cr usage to show your review count, usage-billing status, and, when available, spend and the reset date for the current billing period. cr review --usage and cr --usage are aliases that show the same report instead of starting a review. The usage command requires authentication and is not available for self-hosted logins.

Session handoff commands

Use session handoff commands to move coding-session summaries between local and cloud agents.

Command or option	Description
`cr session import --task-id TASK_ID`	Download the summary for an existing cloud coding task
`cr session export`	Upload the local session summary and create a cloud coding task
`cr session export --task-id TASK_ID`	Upload the local session summary to an existing cloud coding task
`--summary-file <path>`	Use a fresh agent-authored `SUMMARY.md` for export
`--plan-file <path>`	Include the current primary `PLAN.md` when one exists
`--keep local`	Record that the local side should be kept when resolving the handoff

Feedback command

When feedback is enabled for your account, use cr feedback "<message>" to report a wrong, confusing, or useful review finding. Add --agent to emit structured JSON output for an agent workflow. If the command is unavailable, the CLI reports that it is not enabled for your account.

Agent-friendly auth commands

Command	Description
`cr auth login --agent`	Browser-based OAuth login with structured JSON events for agents
`cr auth logout --agent`	Log out with structured JSON events for agents
`cr auth status --agent`	Return authentication status as structured JSON
`cr auth org --agent`	Return organization data as structured JSON for agent workflows; requires an existing browser-based login

For GitHub Actions and other non-interactive environments, use cr auth login --api-key "<key>" and follow the Headless CLI integration guide. cr auth org changes the login/default org for browser-based auth. Review attribution still depends on the current repository, while API-key auth always uses the API key’s organization. If your browser-based session is missing or expired, run cr auth login before cr auth org. The organization command does not start login automatically.

Regional authentication

SaaS login uses the US region when no region is specified or saved. For an EU-hosted CodeRabbit account, select EU during browser or API-key login:

# Browser OAuth
cr auth login --region eu

# Store an EU Agentic API key
cr auth login --region eu --api-key "<key>"

The CLI saves the selected region for later commands. Run cr auth status to verify it, or use --region us during login to switch back to US. Self-hosted authentication uses --self-hosted instead of a SaaS region. For a one-off EU review without storing the API key, pass both options to the review command:

cr review --region eu --api-key "<key>"

The review command rejects --region unless --api-key is provided. A saved EU login does not need either flag on later reviews.

Options

Option	Description
`--agent`	Output structured JSON for agent-driven workflows
`--light`	Request the lighter CLI review policy
`--committed`	Review only committed changes
`--uncommitted`	Review staged changes and unstaged edits to tracked files
`--include-untracked`	Also review non-ignored files not added to Git
`-c, --config <files...>`	Additional instructions for CodeRabbit AI (for example, `CLAUDE.md` or `coderabbit.yaml`)
`--base <branch>`	Base branch for comparison
`--base-commit <commit>`	Base commit on current branch for comparison
`--api-key "<key>"`	Agentic API key for non-browser or headless authentication (auto-detected if logged in via `cr auth login --api-key`)
`--region <us\|eu>`	Region for `cr auth login`; on `cr review`, it requires an inline `--api-key`
`--dir <path>`	Review only Git changes inside a Git worktree or one of its subdirectories
`--show-prompts`	Print saved AI prompts from the most recent local review without running a new review; cannot be combined with `--agent`
`--usage`	Show current billing-period usage instead of running a review; alias of `cr usage`
`-v, --version` (root command)	Show the CLI version

--agent is supported in authentication workflows as well as reviews. cr auth login --agent applies to the browser-based OAuth login flow and is not used with --self-hosted or --api-key login.

PR reviews and CLI reviews will differ, even if run on the same code. CLI reviews optimize for immediate feedback during active development, while PR reviews provide comprehensive team collaboration context and broader repository analysis.

​Commands

​Review modes

​Review scope

​--agent review output

​Diagnostics

​Configuration validation

​Skills command

​Stats command

​Usage command

​Session handoff commands

​Feedback command

​Agent-friendly auth commands

​Regional authentication

​Options

Commands

Review modes

Review scope

`--agent` review output

Diagnostics

Configuration validation

Skills command

Stats command

Usage command

Session handoff commands

Feedback command

Agent-friendly auth commands

Regional authentication

Options