> ## Documentation Index > Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI Command Reference > Reference for supported CodeRabbit CLI commands and commonly used options. ## 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](/cli/cli-with-self-hosted-CodeRabbit) (`--self-hosted`), or [API key](/cli/headless-cli-integration) (`--api-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 ]` | Show findings from the most recent local review with findings for the selected review context | | `cr review findings --clear [--dir ]` | 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](/code/index) 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. ```bash theme={null} 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 -`: ```bash theme={null} 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`](/cli/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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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](/configuration/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: ```bash theme={null} 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): ```bash theme={null} cr config apply proposal.yaml --base --dry-run cr config apply proposal.yaml --base --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](/guides/configuration-overview) for repository settings. ## Configuration validation Use `cr config validate` to check a CodeRabbit YAML file before committing or deploying it. ```bash theme={null} # 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](https://www.coderabbit.ai/integrations/schema.v2.json) 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](/configuration/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. ```bash theme={null} 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](/cli/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 ""` and follow the [Headless CLI integration](/cli/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: ```bash theme={null} # Browser OAuth cr auth login --region eu # Store an EU Agentic API key cr auth login --region eu --api-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: ```bash theme={null} cr review --region eu --api-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 ` | Additional instructions for CodeRabbit AI (for example, `CLAUDE.md` or `coderabbit.yaml`) | | `--base ` | Base branch for comparison; required with `--remote` | | `--remote ` | Review an installed GitHub Cloud repository without a local checkout; requires `--base` and `--source-branch` | | `--source-branch ` | Source branch or full commit SHA for `--remote` | | `--base-commit ` | Base commit on current branch for comparison | | `--api-key ""` | Agentic [API key](/cli/headless-cli-integration) for non-browser or headless authentication (auto-detected if logged in via `cr auth login --api-key`) | | `--region ` | Region for `cr auth login`; on `cr review`, it requires an inline `--api-key` | | `--dir ` | 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.