> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Local CLI review

> Run a fast local cubic AI code review from the command line before you push.

The **cubic CLI** reviews local changes before you push. It finds bugs and generates a prompt that your coding agent can use to fix them.

<Tip>
  We recommend [connecting ChatGPT (Codex) or Claude Code](#bring-your-coding-subscription) for
  access to more capable review models. You can also get started with cubic's included model.
</Tip>

Local reviews give you quick feedback while you work. Use GitHub PR review as the final pass:
it uses a different model and review pipeline for a more thorough review and may find issues
the CLI misses.

## Get started

### 1. Install the CLI

Install the cubic CLI for your operating system.

<Tabs>
  <Tab title="macOS and Linux">
    ```bash theme={null}
    curl -fsSL https://cubic.dev/install | bash
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    npx @cubic-dev-ai/cli install -g
    ```
  </Tab>
</Tabs>

### 2. Sign in

Open a terminal in your Git repository and run:

```bash theme={null}
cubic
```

The first launch opens your browser so you can sign in with your cubic.dev account. If
authentication fails, press `Ctrl+L` in the CLI to log out and sign in again.

<img src="https://mintcdn.com/cubic-2/nl5nAUh5YEMjFC0f/ai-review/images/cli/cli-home.png?fit=max&auto=format&n=nl5nAUh5YEMjFC0f&q=85&s=7488ae65160c88f5325ab57f1d2bb60d" alt="cubic CLI home screen showing review preset options" className="border border-zinc-800 rounded-lg" width="1200" height="864" data-path="ai-review/images/cli/cli-home.png" />

### 3. Run your first review

From your repository, run this command in your terminal to review uncommitted changes:

```bash theme={null}
cubic review
```

To review your branch against its base instead, run:

```bash theme={null}
cubic review -b
```

The CLI detects the base branch automatically. To choose one explicitly, use
`cubic review --base main`, replacing `main` with your base branch.

### 4. Use the findings

The CLI groups findings by priority. Fix the issues yourself or give the generated prompt to
your coding agent. Review the fixes, then run the review again to check them before you push.
After pushing, check cubic's GitHub review for additional findings.

<img src="https://mintcdn.com/cubic-2/nl5nAUh5YEMjFC0f/ai-review/images/cli/cli-results.png?fit=max&auto=format&n=nl5nAUh5YEMjFC0f&q=85&s=4bb0213fd5ab5e58ae5a380cf8bd7a43" alt="cubic CLI review results showing prioritized issues" className="border border-zinc-800 rounded-lg" width="1200" height="864" data-path="ai-review/images/cli/cli-results.png" />

The CLI syncs supported cubic cloud context, including [custom agents](/ai-review/custom-agents),
past feedback, and repository settings. CLI usage appears in your
[analytics dashboard](https://www.cubic.dev/analytics) as **CLI sessions**.

## Bring your coding subscription

Connect your existing **ChatGPT Plus/Pro** or **Claude Code** subscription to use its models
for local reviews. This is optional: cubic handles inference when you use the included model.

<Tabs>
  <Tab title="ChatGPT (Codex)">
    Connect your ChatGPT account to use Codex models with your existing plan:

    ```bash theme={null}
    cubic auth connect codex
    ```

    Sign in through the browser, then choose a Codex model in the CLI.
  </Tab>

  <Tab title="Claude Code">
    Connect your Claude Code account to use Claude models with your existing plan:

    ```bash theme={null}
    cubic auth connect claude-code
    ```

    Choose `opus` for the most thorough review, `sonnet` for everyday reviews, or `haiku` for speed.

    <Accordion title="Why can cubic use my Claude Code subscription?">
      cubic runs your local Claude Code as a subprocess and talks to it over the [Agent Client
      Protocol (ACP)](https://github.com/agentclientprotocol/agent-client-protocol), the same pattern
      [Zed](https://zed.dev/docs/ai/external-agents#claude-agent) uses for its Claude Agent. Your
      Claude Code installation authenticates with Anthropic, makes every model call, and bills you
      directly. cubic never sees, stores, or proxies your credentials, and does not call Claude's API,
      use the Agent SDK, or offer Claude.ai login.

      Reviews are interactive: you start each session and drive it from the UI. cubic does not run
      autonomous loops in the background. This is the "ordinary use of Claude Code" that Anthropic's
      [usage policy](https://code.claude.com/docs/en/legal-and-compliance) permits for Pro/Max
      subscribers.
    </Accordion>
  </Tab>
</Tabs>

In the CLI, press `Ctrl+P` to choose a connected provider, then press `m` to choose a model.
You can switch without signing in again.

Run `cubic auth logout` to disconnect a provider. Disconnecting Claude Code from cubic does
not sign you out of Claude Code.

## Review with your coding agent

[Connect cubic to your IDE](/ide/agent-setup) and [install the skills](/ide/skills#install-skills),
then ask your coding agent to "review my code" to run a local review.

To include local review in your agent's workflow, add this to `AGENTS.md`, `CLAUDE.md`, or
`.cursorrules`:

```markdown theme={null}
## cubic review workflow

Before committing, run `cubic review` to review uncommitted changes.
Fix the validated issues and run the local review again.
Repeat until the local review is clean or only disputed issues remain.

After pushing, wait for cubic's GitHub review and check its comments.
Fix the validated issues and push the changes.
Use GitHub review as the final pass; it may find issues the local review misses.
```

## Command reference

Run `cubic review` without options to review uncommitted changes.

| Task                       | Command                                         |
| -------------------------- | ----------------------------------------------- |
| Review uncommitted changes | `cubic review`                                  |
| Compare with a base branch | `cubic review --base [branch]` (`-b`)           |
| Review a specific commit   | `cubic review --commit <ref>` (`-c`)            |
| Add custom instructions    | `cubic review --prompt "<instructions>"` (`-p`) |
| Return one JSON object     | `cubic review --json` (`-j`)                    |
| Stream JSON events         | `cubic review --output-format stream-json`      |

Omit the branch from `--base` to detect it automatically. The `--base`, `--commit`, and `--prompt` options are mutually exclusive. Use `--output-format text`, `json`, or `stream-json` to select an output format explicitly.

### Output formats

The default text output shows human-readable findings with colored priority labels.

<AccordionGroup>
  <Accordion title="JSON">
    Run `cubic review --json` when an integration needs one JSON object after the review finishes.
  </Accordion>

  <Accordion title="Streaming JSON">
    Run `cubic review --output-format stream-json` when an agent, CI job, or integration needs progress
    before the review finishes. The command writes compact NDJSON events to stdout, including finding
    updates, retries, heartbeats, and a final `review.completed` or `review.failed` event.
  </Accordion>
</AccordionGroup>

## Advanced settings

<AccordionGroup>
  <Accordion title="How do automatic updates work?">
    The CLI checks for a newer version in the background whenever you run a command. When an update is
    available, the CLI installs it before running the command.

    Run `cubic upgrade` to update immediately, or `cubic upgrade <version>` to install a specific
    version.
  </Accordion>

  <Accordion title="How do I disable automatic updates?">
    Add `disable_auto_updates` to `~/.config/cubic/config.json` to receive update notifications without
    installing them automatically:

    ```json theme={null}
    {
      "disable_auto_updates": true
    }
    ```

    Set `CUBIC_DISABLE_AUTOUPDATE=1` to skip both the update check and automatic installation:

    ```bash theme={null}
    export CUBIC_DISABLE_AUTOUPDATE=1
    ```

    This environment variable is useful in CI, on machines without outbound internet, or when you
    need to pin a version.
  </Accordion>

  <Accordion title="How do I control AI attribution tracking?">
    The CLI installs [git-ai](https://usegitai.com) to tag AI-assisted commits with git notes. These
    notes power the [AI coding analytics](/analytics/ai-coding) dashboard. Attribution tracking is
    enabled by default, and git-ai shows an AI-versus-human authorship summary after each commit.

    Set `CUBIC_DISABLE_GIT_AI` during installation to skip git-ai:

    <Tabs>
      <Tab title="macOS and Linux">
        ```bash theme={null}
        curl -fsSL https://cubic.dev/install | env CUBIC_DISABLE_GIT_AI=true bash
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        $env:CUBIC_DISABLE_GIT_AI = "true"
        npx @cubic-dev-ai/cli install -g
        ```
      </Tab>

      <Tab title="Windows Command Prompt">
        ```cmd theme={null}
        set CUBIC_DISABLE_GIT_AI=true
        npx @cubic-dev-ai/cli install -g
        ```
      </Tab>
    </Tabs>

    Manage tracking after installation with `cubic stats`:

    ```bash theme={null}
    cubic stats status
    cubic stats disable
    cubic stats enable
    ```

    `cubic stats disable` removes git-ai hooks and preserves your preference during future upgrades.
    `cubic stats enable` reinstalls git-ai and clears the opt-out preference.
  </Accordion>
</AccordionGroup>

## Limitations

CLI usage is unlimited during alpha, subject to rate limits that ensure fair access.