> 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

Run every SonarQube CLI analysis on your uncommitted, staged, or branch-diff changes, and get server-grade results in your terminal in seconds.

`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 analysis](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) requires a Sonar Vortex subscription.

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

> **Note:** The Vortex analysis portion requires a Vortex subscription on your connection: a SonarQube Cloud organization on an annual Team or Enterprise plan, or the SonarQube Server 2026.5 or newer Enterprise and Data Center editions.

## 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, Codex, Cursor, or Antigravity 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](https://docs.sonarsource.com/sonarqube-cli/quickstart-guide.md).
* You're inside a Git repository (when using the default change-set detection).

To include Vortex analysis in the run, you additionally need one of the following:

* SonarQube Cloud: a connection to SonarQube Cloud (EU or US region) on an annual Team or Enterprise plan with a Vortex subscription.
* SonarQube Server: SonarQube Server 2026.5 or newer Enterprise and Data Center editions with a Vortex subscription.

## 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: changes to tracked files, plus untracked, non-ignored files.                                                       |
| `--staged`        | Only what `git diff --cached` shows.                                                                                                      |
| `--file <path>`   | One or more specific files inside the project root (repeatable), regardless of Git state. A path outside that root fails Vortex analysis. |
| `--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).                                          |

When your repository has no commits yet, the default change set uses staged files from the Git index and untracked, non-ignored files. This lets you run `sonar analyze` before your first commit.

> **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

Vortex 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) to include cross-file findings. Those instructions omit `--project`. The CLI assigns each file to the project that owns it. In a repository with several projects, run the command from a directory that contains every changed file, usually the repository root. See [Files and the project root](#files-and-the-project-root).

### 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), Vortex 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

Within one project, Vortex analysis sends that project's files together in one request. Analyzing them together lets a `DEEP` analysis trace data flows across files. When the files belong to several projects, each project is its own request, so cross-file findings stay inside that project. See [Files and the project root](#files-and-the-project-root).

If a request is too large, the CLI splits that project's files into smaller batches and sends them automatically. Because the split files no longer travel in the same request, cross-file context can be reduced for that run.

## Files and the project root

Vortex analysis matches each file to a project root from the same discovery as [project key auto-detection](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#project-key-auto-detection). For `.sonar-config.json`, that root is the entry's `path`, relative to the repository root. For `sonar-project.properties` or a SonarQube for IDE connected-mode file, it is the directory that contains the file. A known project mapping from `sonar integrate` uses the directory recorded for that project. When the only binding is the Git `origin` remote, the project root is the repository root.

When you omit `--project`, the directory you run from decides which projects are in scope. The deepest project root that contains a file wins.

* From a directory that contains several projects, usually the repository root, one command analyzes each changed file against the project that owns it. Text output groups findings under a header for each project: `<project-key> · N files · N issues`. When more than one project is included, the progress line names the current one (`Project 1/2 · <project-key>`).
* From inside a project, the command analyzes that project and any projects nested under the current directory. A change-set file owned by a project outside that directory is left out of the request. A `--file` path must sit inside the current directory. A path outside it is rejected before analysis starts.

Run the command from a directory that contains every file you want analyzed. When you are not already at the repository root and a change-set file is outside every project mapped from the current folder, the text report counts those files and tells you to rerun from the repository root: `cd <path> && sonar analyze agentic`.

A change-set file that the active connection leaves out is marked in text as `[IGNORED: <reason>]`:

* `binary file`
* `file too large`
* `outside the repository`
* `not in a mapped project`
* `project linked to another server or organization`

When findings are grouped by project, those files appear under a `Not analyzed` header. JSON lists them in `ignored` with `path` and `reason`: `binary`, `oversized`, `outside-repository`, `outside-project`, or `other-connection`. On `sonar analyze --format json` that array is `agentic.ignored`. On `sonar analyze agentic --format json` it is top-level `ignored`. An analyzed file, and a failure, includes `project` when the project is known.

An explicit `--file` that would be left out is an error and exits with code `2`:

* Outside the only project root, one path prints `File must be inside the project root '<project-root>': <path>`. That path is relative to your current directory when the file is inside it. Two or more paths print `Files must be inside the project root '<project-root>':` and list every outside path relative to your current directory.
* Outside every project root in scope, the error is `Files must be inside one of the project roots (<project-roots>):` and lists those paths the same way.
* Owned by a project linked to another server or organization, the error is `Files belong to a project linked to another server or organization than the active connection:` and lists those paths the same way.

Secrets detection on `sonar analyze` still scans the paths you pass and the full change set. Change-set findings are printed relative to the repository root. `--file` findings are printed relative to your current directory. The CLI sends each path to the server relative to that file's project root.

When every Vortex change-set file is excluded, the CLI prints `Vortex analysis: no files to analyze. All change set files were excluded (binary, oversized, or outside the repository or project).` and does not call the server. JSON still lists each excluded file under `ignored`.

Pass `--project` to send every file to that one key. When the key is a project discovery already found, the CLI keeps that project's root. When it names a different key, the CLI uses the repository root, or your current directory when you are outside a git repository.

Each project's files go in their own request, so a `DEEP` analysis traces cross-file issues only inside that project. A request that is too large is split into smaller batches, which can reduce cross-file context for that project.

A per-edit hook analyzes the edited file against the project that owns it. It stays silent when the file is outside the working directory, no project owns it, or the owning project is linked to another connection. Codex's patch hook analyzes the change set the same way and lists each excluded path with its reason. End-of-turn instructions tell the agent to run from a directory that contains every file changed in the turn, usually the repository root. Re-run `sonar integrate` for that agent so an existing install picks up the paragraph.

## Branch context for Vortex analysis

Vortex analysis sends a branch name to SonarQube to associate findings 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 is not available, or you're outside a git repository. In those cases, pass `--branch` if you need branch context on the server.

Because Claude Code post-edit hooks use the same branch resolution, agents do not need to pass `--branch` when they run `sonar analyze agentic`.

## Override the project key

When you omit `--project`, Vortex analysis assigns each file to a project (see [Files and the project root](#files-and-the-project-root) and [Project key auto-detection](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#project-key-auto-detection)). Pass `--project` to pin every file to one key, including when you want to analyze without a saved binding:

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

To persist a binding in the repository instead of passing `--project` each time, run [`sonar link`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-link). Use [`sonar link --monorepo`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-link) when the repository maps several directories.

When `--project` names the discovered project, Vortex analysis keeps that project's root. When it names a different key, file paths use the repository root. See [Files and the project root](#files-and-the-project-root).

## 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, including a `--file` path outside the current directory, outside the projects in scope, or linked to another server or organization.

See [Exit codes](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/exit-codes.md) for the full table.

## Terminal output

`sonar analyze` prints secrets results first, then Vortex analysis when your connection has a Vortex subscription. A clean secrets scan ends with `No secrets found · Nms` (the same summary as [`sonar analyze secrets`](https://docs.sonarsource.com/sonarqube-cli/analysis/secrets-detection.md#terminal-output)). A clean Vortex analysis ends with `No issues found` and the files-analyzed count.

## 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`: Vortex 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`), per-file issues under `agentic.files[].issues[]`, and `project` on a file or failure when the project is known. Change-set files the CLI did not send are under `agentic.ignored[]` (`path` and `reason`: `binary`, `oversized`, `outside-repository`, `outside-project`, or `other-connection`).

```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 a [Claude Code](https://docs.sonarsource.com/sonarqube-cli/integrations/claude-code.md), [GitHub Copilot CLI](https://docs.sonarsource.com/sonarqube-cli/integrations/github-copilot-cli.md), [OpenAI Codex](https://docs.sonarsource.com/sonarqube-cli/integrations/codex.md), [Cursor](https://docs.sonarsource.com/sonarqube-cli/integrations/cursor.md), or [Antigravity](https://docs.sonarsource.com/sonarqube-cli/integrations/antigravity.md) integration, the agent can run `sonar analyze` itself. For Claude Code and Codex, `PostToolUse` hooks run fast analysis after each edit. A per-edit hook analyzes the edited file against the project that owns it, and stays silent when no project of the active connection owns the file. End-of-turn instructions in `CLAUDE.md` or `AGENTS.md` tell the agent when to run `DEEP` analysis from a directory that contains every changed file. See [Files and the project root](#files-and-the-project-root). For GitHub Copilot CLI, Cursor, and Antigravity, end-of-turn instructions tell the agent when to run analysis. For example, ask: *"Run `sonar analyze --staged` and show me the BLOCKER findings."*\`

If Vortex analysis reports that no project is configured, those instructions tell the agent to stay silent for the rest of the session instead of repeating a skip notice. After you ask for Vortex analysis or configure a project, the agent runs analysis again.

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

* [AI remediation](https://docs.sonarsource.com/sonarqube-cli/analysis/ai-remediation.md)
* [Secrets detection](https://docs.sonarsource.com/sonarqube-cli/analysis/secrets-detection.md)
* [Commands reference](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md)
* [Output formats](https://docs.sonarsource.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
