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`	Create or update repository YAML settings through guided setup
`cr config --agent`	Inspect repository configuration as JSON without prompts or writes
`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 review findings --clear [--dir <path>]`	Dismiss all stored findings for the current review scope
`cr skills`	Install or update verified CodeRabbit skills for supported coding agents
`cr usage`	Show billing-period review usage and spend when available
`cr update`	Check for and install the latest CLI version

Cloud coding commands

CLI 0.8.1 groups cloud Coding Agent commands under cr code. Run cr update to update and cr code --help to see the available commands.

Continue a local session in the cloud

Run the handoff command from a clean Git checkout on a branch with an origin remote. Sign in with cr auth login and make sure you have access to Coding Agent and the repository. The cloud task must be able to fetch the selected commit. Keep summary and plan files outside the repository, or commit them first, so they do not leave untracked changes.

cr code handoff --summary /tmp/session-summary.md
cr code handoff --summary /tmp/session-summary.md --plan /tmp/session-plan.md

To read the summary from standard input, use --summary -:

cat /tmp/session-summary.md | cr code handoff --summary -

The command creates a new cloud task and uploads your summary, optional plan, and a discovered session transcript when available. Review the material before transferring it. A missing transcript or failed optional transcript upload produces a warning and does not prevent handoff with the summary and plan. Each attachment is limited to 25 MiB. The result shows the branch, commit, transferred filenames, and a link to open the task. Cloud startup still needs to verify the commit and load the files; task creation does not mean the coding work has finished. cr handoff remains supported with the same options, although it is hidden from top-level help. In 0.8.1, its result spans multiple lines and no longer includes the uploaded byte count. Progress messages also drop the previous [handoff] prefix. Scripts that parse that human-readable output need adjustment.

Import cloud skills

Cloud skill import requires Coding Agent access for the selected organization and a CodeRabbit SaaS user login. Availability depends on your organization’s access and rollout settings. API-key authentication and self-hosted CodeRabbit are unsupported. This command uploads skills to the cloud Coding Agent library; cr skills installs CodeRabbit skills for your local coding agent. Run cr code skills import interactively to choose a local agent and select skills, or provide a skill folder or its SKILL.md file directly:

cr code skills import
cr code skills import ./my-skill
cr code skills import ./my-skill/SKILL.md --scope personal

Review the selected files and destination before confirming the upload. New skills are personal within the selected organization by default. Use --scope organization to share an imported skill with that organization. Importing a skill you own with the same name publishes a new version. For a non-interactive import, specify a path and --yes to authorize its upload. Use cr auth org to select the destination organization. If the CLI requests a current login, run cr auth login again and retry.

Stored review findings

cr review findings shows the most recent local session that contains findings for the current review directory, branch, and base branch. An empty review can still show a reminder about earlier findings; that reminder does not mean the latest review found new issues. Up to ten sessions are retained per scope, with no time-based expiry.

Clearing stored findings requires CLI 0.7.7 or later. Run cr update to update.

After fixing or rejecting earlier findings, clear them with:

cr review findings --clear
cr review findings --clear --dir src

--clear dismisses findings from every retained session in the selected scope. Other repositories, branches, base branches, and review directories are unchanged. A review run with --dir src has a separate scope from a whole-repository review. The command runs without a confirmation prompt and prints the review directory, current branch, and base branch it affected. Findings are dismissed, not deleted; incremental review state is preserved. Cleared findings stop appearing in both cr review findings and the zero-finding reminder. Repeating the command is safe, and future reviews can report new findings normally. If some findings cannot be updated, the command reports the affected scope and counts, then exits with code 1. Successfully dismissed findings remain dismissed; retry after correcting the local storage permissions.

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.

The default review uses the net changes for the selected Git comparison, so overlapping committed and uncommitted edits are reviewed together. --committed reads reviewed file content and automatically discovered configuration from the selected Git snapshot. Explicit --config files are read from the filesystem. Saved context for incremental reviews is reset when the comparison base changes. On upgrade to CLI 0.7.7, checkpoints from earlier versions reset once; the next review establishes a new checkpoint.

Remote reviews without a checkout

With CLI 0.7.7 or later, review an installed GitHub repository from any directory by naming its base and source refs:

cr review --remote owner/repo --base main --source-branch feature --agent

--remote accepts owner/repo or a GitHub HTTPS repository URL. Both --base and --source-branch are required. The source must be a branch name or a full 40-character commit SHA; source tags are unsupported. The server compares the source with the merge base and reads repository content at the resolved source commit, without uploading local files. Remote reviews require GitHub Cloud, a repository installed in the active CodeRabbit organization, and browser-based CodeRabbit SaaS authentication or an Agentic API key. Private repositories also require the authenticated user’s repository read access. GitHub Enterprise, self-hosted CodeRabbit, and other providers are unsupported. Comparisons with 300 or more changed files are rejected because the provider response may be incomplete. Narrow the branch comparison before retrying. Remote reviews cannot be combined with local selectors such as --dir, --committed, --uncommitted, --include-untracked, or --base-commit, or with --show-prompts. The server reads configuration from the reviewed repository; local --config files are ignored. Remote findings appear in the existing plain or agent output stream, without locally generated diff snippets or local findings history. For agent output, review_context includes remote, currentBranch, and baseBranch and omits workingDirectory.

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

Failed or incomplete reviews

Starting with CLI 0.7.7, failed or incomplete reviews exit with code 1. Treat the process exit code and completion outcome as part of the result; receiving findings does not prove that the whole review completed. An agent complete event can still have status: "review_completed" when the review failed or missed files. Inspect its outcome, message, and unreviewedFileCount when present: outcome: "failed" or a positive unreviewedFileCount means the run was incomplete. outcome: "completed_with_warnings" with no files left to review does not by itself indicate failure. For local reviews, findings received before a failure remain available, and the last successful incremental checkpoint is preserved. Retry after resolving the reported error. A no-change result with status: "review_skipped" remains a successful skip.

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 setup

Guided setup requires CLI 0.7.7 or later and an interactive terminal inside a Git repository:

cr config
cr config --detailed

Standard setup creates or updates the review style. Manual setup, also available with --detailed, lets you configure review style and path instructions. The command creates .coderabbit.yaml at the repository root, or updates an existing .coderabbit.yaml or .coderabbit.yml. It validates against the current official schema, previews the changes, and asks before saving. Commit and push the configuration through your normal workflow to use it for pull request reviews. If both YAML filenames exist, resolve the duplicate before setup. Guided setup also refuses to replace a symbolic link, override a TypeScript-only configuration with YAML, or edit a file that delegates through remote_config; update the existing configuration source instead.

Agent-guided setup

Use structured output to inspect configuration or prepare a Standard proposal without writing files:

cr config --agent
cr config --agent --generate
cr config --agent --generate --profile assertive

--agent returns the active configuration, whether it can be edited, and its content hash as baseHash. Adding --generate returns a validated proposal with before and after YAML. Supported profiles are chill, quiet, assertive, and default; default removes the explicit profile setting. These commands do not save the proposal. For an automated apply workflow, save the proposed YAML to a file and use the baseHash returned by inspection (none for a new file):

cr config apply proposal.yaml --base <baseHash> --dry-run
cr config apply proposal.yaml --base <baseHash> --yes

Preview and obtain approval for the proposed settings before applying. Apply validates the complete proposal and refuses it if the repository configuration has changed since inspection. A dry run leaves the file unchanged.

Configuration discovery during local reviews

Without explicit --config files, local reviews look for .coderabbit.yaml, .coderabbit.yml, coderabbit.yaml, coderabbit.yml, then .coderabbit.config.ts, in that order. For each filename, the CLI checks the review directory before the Git repository root and uses the first readable match. YAML therefore takes precedence over TypeScript. TypeScript discovery requires CLI 0.7.7 or later. YAML validation and guided YAML setup do not evaluate or edit .coderabbit.config.ts. See the configuration overview for repository settings.

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.

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; required with `--remote`
`--remote <owner/repo>`	Review an installed GitHub Cloud repository without a local checkout; requires `--base` and `--source-branch`
`--source-branch <ref>`	Source branch or full commit SHA for `--remote`
`--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.

Command-Line Review Tool

IDE Extension

CLI Command Reference

Commands

Cloud coding commands

Continue a local session in the cloud

Import cloud skills

Stored review findings

Review modes

Review scope

Remote reviews without a checkout

`--agent` review output

Failed or incomplete reviews

Diagnostics

Configuration setup

Agent-guided setup

Configuration discovery during local reviews

Configuration validation

Skills command

Stats command

Usage command

Agent-friendly auth commands

Regional authentication

Options

​Commands

​Cloud coding commands

​Continue a local session in the cloud

​Import cloud skills

​Stored review findings

​Review modes

​Review scope

​Remote reviews without a checkout

​--agent review output

​Failed or incomplete reviews

​Diagnostics

​Configuration setup

​Agent-guided setup

​Configuration discovery during local reviews

​Configuration validation

​Skills command

​Stats command

​Usage command

​Agent-friendly auth commands

​Regional authentication

​Options

Commands

Cloud coding commands

Continue a local session in the cloud

Import cloud skills

Stored review findings

Review modes

Review scope

Remote reviews without a checkout

`--agent` review output

Failed or incomplete reviews

Diagnostics

Configuration setup

Agent-guided setup

Configuration discovery during local reviews

Configuration validation

Skills command

Stats command

Usage command

Agent-friendly auth commands

Regional authentication

Options