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

# Headless CLI integration

> Authenticate CodeRabbit CLI non-interactively in headless and bot-driven environments using an Agentic API key. Use this flow in CI runners, remote bots, or any automation pipeline where browser-based sign-in is not available.

## Before you start

<Steps>
  <Step title="Enable the Usage-based Add-on">
    The non-interactive API-key flow requires an **Agentic API key**. Enable the [Usage-based Add-on](/management/usage-based-addon) first so your organization can generate and use one for CLI reviews.
  </Step>

  <Step title="Create an Agentic API key">
    Go to [API Keys](https://app.coderabbit.ai/settings/api-keys) in the CodeRabbit dashboard and generate an **Agentic API key** for the organization that should power your CLI reviews.

    API-key authentication always uses that key's organization for billing and review behavior. Browser-based organization selection does not apply in this mode.
  </Step>

  <Step title="Store the key as a secret">
    Save the key in your automation platform as a secret such as `CODERABBIT_API_KEY`, then expose it as an environment variable wherever your automation runs.
  </Step>

  <Step title="Install the CodeRabbit CLI">
    Make the CLI available in the environment using your preferred install method.

    <CodeGroup>
      ```bash Installation script theme={null}
      curl -fsSL https://cli.coderabbit.ai/install.sh | sh
      ```

      ```bash Homebrew theme={null}
      brew install coderabbit
      ```
    </CodeGroup>
  </Step>
</Steps>

## Headless setup

<Tabs borderBottom>
  <Tab title="Single command">
    Pass the key directly to the command:

    ```bash theme={null}
    coderabbit review --api-key "$CODERABBIT_API_KEY"
    ```
  </Tab>

  <Tab title="Authenticate first (chain of commands)">
    Authenticate once so that all later commands reuse the stored key automatically:

    ```bash theme={null}
    coderabbit auth login --api-key "$CODERABBIT_API_KEY"
    ```

    Verify authentication:

    <CodeGroup>
      ```bash Plain terminal output theme={null}
      coderabbit auth status
      ```

      ```bash Agent-readable checks theme={null}
      coderabbit auth status --agent
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Common automation patterns

Use `--agent` when another tool needs structured output:

```bash theme={null}
coderabbit review --agent
```

Use `--plain` when you want readable logs in the workflow output:

```bash theme={null}
coderabbit review --plain
```

If your workflow edits code in place and wants feedback on the current working tree, use `--type uncommitted`.

```bash theme={null}
coderabbit review --type uncommitted
```

If your workflow compares a branch against a base branch, set the base explicitly:

```bash theme={null}
coderabbit review --agent --base main
```

`cr` is the short alias for `coderabbit`, so `cr review --agent` and `coderabbit review --agent` work the same way.

If the review scope has no file changes, the CLI exits cleanly. In `--agent` mode the `complete` event has `status: "review_skipped"` and `findings: 0`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="User API key rejected">
    If authentication fails with a message saying user API keys are not supported, generate an **Agentic API key** instead. The CLI validates the key before storing it locally and rejects unsupported key types.
  </Accordion>

  <Accordion title="No stored API key found">
    If a later review step says no stored API key was found, make sure the `coderabbit auth login --api-key` step ran successfully earlier in the same environment and that the secret was exposed to that step.
  </Accordion>

  <Accordion title="Interactive mode does not work with API-key auth">
    API-key authentication works with the plain and agent review flows. Do not use `--interactive` in headless environments.
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={1}>
  <Card title="Usage-based Add-on" href="/management/usage-based-addon" icon="badge-dollar-sign" horizontal>
    Enable credits, manage billing, and understand how CLI reviews consume usage
  </Card>

  <Card title="CLI Command Reference" href="/cli/reference" icon="terminal" horizontal>
    Review authentication commands, review modes, and CLI options
  </Card>

  <Card title="Codex integration" href="/cli/codex-integration" icon="bot" horizontal>
    Combine headless CLI authentication with Codex-driven implementation and review loops
  </Card>
</CardGroup>