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.

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

• 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

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

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):

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 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):

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

Use it from an AI agent

Once you've installed the Claude Code, GitHub Copilot, or OpenAI Codex 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

• AI remediation

• Secrets scanning

• Commands reference

• Output formats