> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-cli/analysis/analyzing-local-changes.md).

# Analyzing local 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 on the files in your local change set and returns results in seconds without waiting for a full CI scan. Secrets detection works with SonarQube Cloud, SonarQube Server, or no server connection. [Sonar Vortex agentic analysis](/agent-centric-development-cycle/verify/sonar-vortex-agentic-analysis.md) requires SonarQube Cloud.

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

> **Note:** The agentic analysis portion requires a SonarQube Cloud organization with agentic analysis enabled.

## 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-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 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>`   | One or more specific files (repeatable), regardless of Git state.                                |
| `--base <ref>`    | Everything that changed in your branch vs. the named ref (for example, `--base main`).           |
| `--depth <depth>` | Analysis depth: `STANDARD` (fast) or `DEEP` (cross-file). See [Analysis depth](#analysis-depth). |

> **Note:** `--branch` (set the branch name reported to SonarQube) is available on `sonar analyze agentic`, not on the bare `sonar analyze` command. When you omit `--branch`, the CLI auto-detects your current git branch when you're on a named branch. Pass `--branch` to override detection, for example, `sonar analyze agentic --branch feature/x --staged`.

## Analysis depth

Agentic analysis supports two depths:

| Depth      | What it does                                                           | Default when                                                       |
| ---------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `STANDARD` | Fast analysis focused on the file or files you send.                   | You pass exactly one `--file`.                                     |
| `DEEP`     | Cross-file analysis that can surface findings spanning multiple files. | Change-set detection (no `--file`), or two or more `--file` paths. |

Override the default with `--depth STANDARD` or `--depth DEEP`. Per-edit agent hooks use `STANDARD` for speed; end-of-turn agent instructions tell agents to always pass `--depth DEEP` (even for a single file) so cross-file findings are included.

### Examples

```bash
sonar analyze                          # secrets + agentic on local change set (DEEP)
sonar analyze --staged                 # staged only
sonar analyze --file src/app.ts        # one file (STANDARD by default)
sonar analyze --file src/a.ts --file src/b.ts   # two files (DEEP)
sonar analyze --base main              # everything different from main
sonar analyze --project my-org_my-app  # override auto-detected project key
sonar analyze agentic --branch feature/x  # set branch context on agentic only
sonar analyze agentic --staged         # agentic only, staged files
sonar analyze agentic --depth DEEP --file src/a.ts --file src/b.ts  # explicit multi-file DEEP
```

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

## How files are sent to the server

Agentic analysis sends your change set to the server in a single multi-file request. Analyzing the files together lets a `DEEP` analysis trace data flows across them and catch cross-file issues that a file-by-file scan would miss.

If the request is too large, the CLI splits the files into smaller batches and sends them automatically, so large change sets are analyzed without you having to split them yourself. Because the split files no longer travel in the same request, cross-file context can be reduced for that run.

## Branch context for agentic analysis

Agentic analysis sends a branch name to SonarQube Cloud so findings are associated with the right branch. When you omit `--branch`, the CLI auto-detects the current git branch from the repository you're in. Explicit `--branch` always wins.

Auto-detection is skipped when you're on a detached HEAD, git isn't available, or you're outside a git repository. In those cases, pass `--branch` if you need branch context on the server.

Claude Code post-edit hooks use the same branch resolution, so agents don't need to pass `--branch` when they run `sonar analyze agentic`.

## Override the project key

The CLI auto-detects your project from `sonar-project.properties`, or `.sonarlint/connectedMode.json`. If detection picks the wrong one, or you want to run agentic analysis without an installed project integration, pass `--project` on `sonar analyze` or `sonar analyze agentic`:

```bash
sonar analyze --project my-org_my-app
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-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 combined report with three top-level keys:

* `secrets` — local secrets scan results (`issues`, `summary`, and optional `warnings` or `error`)
* `agentic` — Agentic Analysis results when available (`files`, `summary`, `analysisDepth`, and related fields)
* `messages` — informational lines that would appear in text mode

Each entry in `secrets.issues[]` includes `ruleKey`, `description`, `file`, a nested `location` object (`startLine`, `startColumn`, `endLine`, `endColumn`), and optionally `maskedSecret`. Advisory scan problems (for example, a partial auth failure) surface in `secrets.warnings[]` without aborting the scan. In text mode, the same advisories print as `Scan warning:` lines.

The `agentic` section includes `analysisDepth` (`STANDARD` or `DEEP`) and per-file issues under `agentic.files[].issues[]`.

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

## Use it from an AI agent

Once you've installed the [Claude Code](/sonarqube-cli/integrations/claude-code.md), [GitHub Copilot CLI](/sonarqube-cli/integrations/github-copilot-cli.md), or [OpenAI Codex](/sonarqube-cli/integrations/codex.md) integration, the agent can run `sonar analyze` itself. For Claude Code and Codex, this happens automatically via `PostToolUse` hooks; for GitHub Copilot CLI, it runs on request. 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-cli/analysis/ai-remediation.md)
* [Secrets detection](/sonarqube-cli/analysis/secrets-detection.md)
* [Commands reference](/sonarqube-cli/using-sonarqube-cli/commands.md)
* [Output formats](/sonarqube-cli/using-sonarqube-cli/output-formats.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.