# Analyzing local changes

> **Warning:** This product is in Beta stage and we may release breaking changes.

`sonar analyze` is the fastest way to know whether the change you're about to commit introduces new issues. With no subcommand, it runs every analysis the CLI supports, including secrets scanning and [Agentic Analysis](https://docs.sonarsource.com/agent-centric-development-cycle/features/agentic-analysis), on the files in your local change set, and returns results in seconds without waiting for a full CI scan.

To run only Agentic Analysis (no local secrets scan), use `sonar analyze agentic`.

> **Note:** **Agentic Analysis is SonarQube Cloud only.** Secrets scanning runs on SonarQube Cloud and SonarQube Server, but the Agentic Analysis portion of `sonar analyze` requires SonarQube Cloud; it's not yet supported against self-hosted SonarQube Server instances.

> **Warning:** **`sonar verify` is deprecated.** It runs Agentic Analysis only and prints a deprecation warning. Use `sonar analyze` (all analyses) or `sonar analyze agentic` (Agentic Analysis only) instead.

## When to use it

* **Before a commit.** Catch new issues you introduced in your in-flight work, before the rest of the team sees them in CI.
* **Before a pull request.** Confirm the change set is clean and the PR will pass quality gates.
* **From an AI agent.** Once Claude Code, Copilot, or Codex is integrated, the agent can run `sonar analyze` on your behalf and act on the results.

`sonar analyze` is **not** a replacement for the SonarScanner CLI in CI/CD. SonarScanner scans the entire project and is the source of truth for branch and PR analyses. `sonar analyze` is a fast preview for the developer, scoped to local changes.

## Prerequisites

* [The SonarQube CLI is installed and authenticated](/sonarqube-developer-tools/sonarqube-cli/quickstart-guide.md).
* You're inside a Git repository (when using the default change-set detection).

To include Agentic Analysis in the run, you additionally need:

* A connection to SonarQube Cloud (EU or US region).
* An organization with SonarQube Agentic Analysis enabled.

## Pick what to analyze

`sonar analyze` figures out which files to send to the server based on the flags you pass.

| Flag            | What it analyzes                                                                       |
| --------------- | -------------------------------------------------------------------------------------- |
| (none)          | Your local change set: uncommitted + unstaged changes vs. the branch base.             |
| `--staged`      | Only what `git diff --cached` shows.                                                   |
| `--file <path>` | A single file, regardless of Git state.                                                |
| `--base <ref>`  | Everything that changed in your branch vs. the named ref (for example, `--base main`). |

> **Note:** `--branch` (set the branch name reported to SonarQube) and `--project` are available on `sonar analyze agentic`, not on the bare `sonar analyze` command. Combine them with the flags above, for example `sonar analyze agentic --branch feature/x --staged`.

### Examples

```bash
sonar analyze                          # secrets + agentic on local change set
sonar analyze --staged                 # staged only
sonar analyze --file src/app.ts        # one file
sonar analyze --base main              # everything different from main
sonar analyze agentic --branch feature/x  # set branch context on agentic only
sonar analyze agentic --staged         # agentic only, staged files
```

## Large change-set protection

To prevent runaway scans on accidental huge diffs (typically when you've branched off the wrong base), Agentic Analysis prompts for confirmation when the change set exceeds **50 files**.

* Pass `--force` to skip the prompt.
* Pass `--format json` to suppress prompts entirely (useful for scripts and AI agents).

```bash
sonar analyze --base main --force
sonar analyze --base main --format json
```

## Override the project key

The CLI auto-detects your project from `sonar-project.properties`, or `.sonarlint/connectedMode.json`. If detection picks the wrong one, override it with `sonar analyze agentic` (the `--project` flag isn't available on the bare `sonar analyze` command):

```bash
sonar analyze agentic --project my-org_my-app
```

## Exit codes

* `0`: analysis succeeded and no new issues were reported.
* `51`: analysis succeeded but new issues were reported on the change set.
* `1`: analysis failed (server error, authentication problem, etc.).
* `2`: invalid flags.

See [Exit codes](/sonarqube-developer-tools/sonarqube-cli/using-sonarqube-cli/exit-codes.md) for the full table.

## Output formats

`sonar analyze` outputs human-readable text by default. Pass `--format json` for a machine-readable result to pipe into other tools (or feed into an AI agent):

```bash
sonar analyze --staged --format json | jq '.issues[] | select(.severity=="BLOCKER")'
```

## Use it from an AI agent

Once you've installed the [Claude Code](/sonarqube-developer-tools/sonarqube-cli/integrations/claude-code.md), [GitHub Copilot](/sonarqube-developer-tools/sonarqube-cli/integrations/github-copilot.md), or [OpenAI Codex](/sonarqube-developer-tools/sonarqube-cli/integrations/codex.md) integration, the agent can run `sonar analyze` itself, automatically for Claude Code (via its `PostToolUse` hook), or on request for Copilot and Codex. For example, ask: *"Run `sonar analyze --staged` and show me the BLOCKER findings."*

## Related pages <a href="#related-pages" id="related-pages"></a>

* [AI remediation](/sonarqube-developer-tools/sonarqube-cli/analysis/ai-remediation.md)
* [Secrets scanning](/sonarqube-developer-tools/sonarqube-cli/analysis/secrets-scanning.md)
* [Commands reference](/sonarqube-developer-tools/sonarqube-cli/using-sonarqube-cli/commands.md)
* [Output formats](/sonarqube-developer-tools/sonarqube-cli/using-sonarqube-cli/output-formats.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-developer-tools/sonarqube-cli/analysis/analyzing-local-changes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.