Agent mode output and exit codes

Use agent mode when a coding agent or script consumes CodeRabbit CLI results. This page describes the output contract and exit codes. For the options of each command, see the CLI command reference.

​

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: In earlier versions, comment is included only when codegenInstructions is empty. The added fields do not change how existing consumers read fix instructions. 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. For a remote review, review_context includes remote, currentBranch, and baseBranch and omits workingDirectory.

​

Duration and repeated reviews

In CLI 0.9.0 or later, review_context.expectedDuration tells the caller how long to wait. Allow at least 15 minutes or run the command in the background, and keep reading heartbeat events. If a signal interrupts an active review, the CLI attempts to emit an error record with errorType: "interrupted", elapsedSeconds, and retry guidance before exiting. When the server reuses an existing review, the complete event includes reused: true. Treat this as a reused result rather than proof that a new review ran. After a rate limit with a known wait time, rerunning the command can return the same rate-limit error and remaining wait without reconnecting. The local wait is capped at 15 minutes. Wait for the reported time instead of retrying in a loop. Eligible usage-based reviews with --use-credits bypass this local wait; the flag still authorizes paid work under your organization’s billing settings.

​

Reviews with too many files

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

​

Reviews with no changes

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.

​

Results that could not be saved locally

In CLI 0.9.0 or later, a complete event can include persistence with status: "failed" and an errorCode. Keep the findings from the current stream: they may not be available through cr review findings. Check local storage permissions and free space before the next review. A local save failure does not by itself mean the server review failed; continue to check the completion outcome and exit code.

​

Exit codes

A review that is skipped because the selected scope has no changes is a successful run and does not exit with code 1.

​

Agent-friendly authentication

cr auth login --agent applies to the browser-based OAuth login flow and is not used with --self-hosted or --api-key login. For GitHub Actions and other non-interactive environments, use cr auth login --api-key "<key>" and follow the Headless CLI integration guide.

​

Structured output from other commands

Several other commands accept --agent for structured output. Most are described in the CLI command reference:

• cr config --agent inspects repository configuration. See agent-guided setup.
• cr skills --agent previews skill installation for approval. See CodeRabbit Skills.
• cr usage --agent returns one usage event.
• cr pullrequest --agent returns newline-delimited JSON for pull request output.
• cr code handoff --agent returns newline-delimited JSON for agent workflows.
• With CLI 0.9.0 or later, the cloud task commands under cr code, such as cr code ls, cr code new, and cr code resume, return newline-delimited JSON. Pass --agent explicitly, and before --plan for cr code new, so that argument errors are also JSON. Several of these commands change state: cr code new starts a billed task, and cr code push pushes changes. See drive tasks from scripts and coding agents.

​

What’s next