Overview

Plug the SonarQube CLI into your editor, AI coding assistants, and Git workflow so analysis runs automatically.

The SonarQube CLI ships first-class integrations for the tools you use every day. Run sonar integrate with no subcommand to pick a tool from an interactive list, or call a subcommand directly (for example, sonar integrate claude). Each integration connects SonarQube to one of these tools. It installs secrets-detection hooks, configures the MCP server where applicable, and sets up Vortex analysis features on SonarQube Cloud.

What's available

Claude CodeCursorGitHub Copilot CLIGoogle AntigravityOpenAI CodexGit hooks

Project versus global scope

Every sonar integrate command (bare or subcommand) installs at project scope (inside the current repository) or global scope (in your user home, applying across projects on your machine):

Scope	Flag	Where files are installed	When to use
Project	none (default)	Inside your repository (.claude/, .copilot/, .cursor/, Codex config, .git/hooks/)	Per-repo configuration. The hook ships with the repo and applies only when working in that project.
Global	--global	In your user home (~/.claude/, ~/.copilot/, ~/.cursor/, ~/.codex/, ~/.sonar/sonarqube-cli/hooks/)	Apply once, get the integration across every project on your machine. Recommended for individual developers and for security baselines.

The --project / -p flag sets the SonarQube project key. Passing it implies project scope and skips the scope prompt. When you omit it, the CLI resolves the project from sonar-project.properties, SonarQube for IDE connected mode, or the git origin remote when the repository is bound on SonarQube.

In an interactive terminal, when you omit both --global and --project, the CLI shows the connection and project preflight summary, then asks where to install. Choose This project for the current directory, or Global for your user home.

In non-interactive mode (including when you authenticate with environment variables), scope defaults to project when you don't pass --global. The CLI logs an info line recording that default.

CLI commands (sonar context, sonar analyze agentic) and Git hooks work from any linked git worktree in the same repository, because the CLI resolves them from the state stored under ~/.sonar/. Agent integration files written to your project directory (hook config, instructions, skills) are not automatically available in a new worktree. See the Git worktrees page for setup options.

If you install a global integration first and then run the same sonar integrate command in a project, the CLI detects the existing global setup and skips redundant hook installation.

Note: A project-scoped agent integration writes skill files, hook configuration, and instructions into the repository's working directory. These files don't appear in a new worktree unless you commit them, therefore the integration may not work by default. See Git worktrees for setup options.

What gets installed

AI agent integrations (sonar integrate claude, copilot, codex, cursor, and antigravity) install three categories of features, though the exact mechanism varies by agent:

• Secrets-scanning hook(s). For Claude Code, a UserPromptSubmit hook (scans the prompt you send to Claude) and a PreToolUse hook (runs before file reads/writes). For GitHub Copilot CLI, a pre-tool-use hook. For OpenAI Codex, a UserPromptSubmit hook (scans the prompt before it is sent to Codex), plus instructions to scan files for secrets before reading them. For Cursor, a beforeSubmitPrompt hook plus beforeReadFile and preToolUse hooks that scan files before the agent reads them. These all block any operation that would expose a secret. Powered by sonar analyze secrets.
• MCP server configuration. Lets the agent call SonarQube directly to fetch projects, issues, and rules.
• Vortex (SonarQube Cloud only). One install adds Vortex analysis and a Vortex context skill together for every supported agent integration. Delivery varies by agent:

  • Claude Code: a shared PostToolUse hook for fast STANDARD analysis after each edit or write and for forwarding Bash, PowerShell, Monitor, and Read tool results to Vortex context when available; a PostToolUseFailure hook for failed tool calls from those tools; end-of-turn DEEP instructions in CLAUDE.md; and a Vortex context skill
  • OpenAI Codex: a PostToolUse hook on apply_patch for DEEP change-set analysis and a Vortex context skill
  • GitHub Copilot CLI, Cursor, and Google Antigravity: end-of-turn Vortex analysis instructions or rules and a Vortex context skill Setup checks plan entitlement only; reaching your usage limit does not block installation. Vortex is project-scoped: --global installs skip it.

sonar integrate git installs code scanning hooks at the Git layer, so commits and pushes are blocked even outside of an AI agent's session. Every hook runs secrets scanning; you can optionally enable dependency-risks scanning on the pre-commit hook. See Git hooks.

Git worktrees

A project-scoped agent integration writes its files into the current working directory. Git worktrees each have their own working directory, and Git populates a new worktree only from the files committed on the branch you check out; integration files you have not committed don't appear in a newly created worktree.

sonar context, sonar analyze agentic, and native Git hooks installed with sonar integrate git still work from any worktree because the CLI resolves them from state stored outside the working directory (under ~/.sonar) and from the repository's shared .git/hooks directory. A new worktree is missing the agent files written into the repository (skills, hook configuration, and instructions or rules) unless you've committed them. To set them up, either commit the generated integration files (for example, .claude/, CLAUDE.md, .cursor/, .github/, .agents/, or AGENTS.md), or run the integration again from inside the worktree:

cd ../my-worktree
sonar integrate <agent> --non-interactive

Replace <agent> with the integration you use: claude, cursor, codex, antigravity, copilot, or git. Running the command again is safe; it recognizes an existing setup and updates it in place.

Automate setup with a post-checkout hook

To set up the integration automatically whenever you create a worktree, add a Git post-checkout hook. Git runs it after git worktree add completes, with the new worktree as the working directory. Save the following as post-checkout in your repository's hooks directory (see Where to place the hook), then make it executable with chmod +x:

#!/bin/sh
# post-checkout — set up the SonarQube integration in a newly created Git worktree.

# Replace with the agent you use: claude, cursor, codex, antigravity, copilot, or git.
AGENT="<agent>"

# `git worktree add` does a fresh checkout (the previous HEAD is the null object ID)
# into a linked worktree (its `.git` is a file, not a directory). Skip anything else.
[ -f .git ] || exit 0
[ "$1" = "0000000000000000000000000000000000000000" ] || exit 0

sonar integrate "$AGENT" --non-interactive

Replace <agent> in the AGENT variable with the integration you use, and add a sonar integrate line for each additional agent. The two checks limit the hook to worktree creation: the null previous HEAD marks a fresh checkout (an ordinary branch switch or file checkout keeps the current HEAD), and the .git file marks a linked worktree (both the main checkout and a fresh clone use a .git directory). The hook runs sonar integrate in non-interactive mode; make sure sonar is on your PATH and the CLI is authenticated first (see Quickstart guide).

Where to place the hook

The location depends on whether your repository uses a custom hooks path:

git config core.hooksPath

• If the command prints nothing, place the hook at .git/hooks/post-checkout. Because linked worktrees share the main repository's .git directory, you install it once from the main checkout, and it applies to every worktree.
• If the command prints a path (for example, when you install global Git hooks with sonar integrate git --global, or you use Husky), place the hook in that directory instead. A hook in .git/hooks does not run when core.hooksPath is set.

Install confirmation

After you select which features to install (or when non-interactive mode accepts every eligible feature), the CLI shows a What will be installed summary. It lists each accepted feature with a short description of what it does.

In interactive mode, press Enter when prompted to proceed with installation. In non-interactive mode (--non-interactive or environment-variable auth), the summary is printed and installation proceeds without a confirmation prompt.

Removing installed features

When you re-run a sonar integrate command interactively, the CLI asks whether to keep each feature that's already installed for that integration. Decline to keep a feature and the CLI warns you, then asks you to confirm removal. Confirming tears down the feature's files and configuration, prunes the recorded state, and uninstalls auxiliary binaries that no longer have any referrer.

• Installed features prompt <name> (currently installed) Keep? (default Yes)
• Declining shows a warning, then Proceed with removal? (default Yes)
• The completion summary lists removed features under Removed
• Config files that held only Sonar-managed content (for example, .mcp.json or hook JSON) are deleted instead of left empty; files with your own or other integrations' content are kept with Sonar entries pruned
• Features that aren't installed yet follow the existing opt-in install flow
• Container features (for example, the git pre-commit hook group) are removed as a whole; the CLI doesn't prompt per subfeature
• In non-interactive mode (--non-interactive or environment-variable auth), the CLI never offers to remove features; it keeps existing installs and only adds what's missing

To remove everything at once, use Reset the CLI or the manual steps in Uninstalling.

When Vortex analysis is no longer available

When Vortex analysis fails with HTTP 403, the CLI re-checks your organization's Vortex entitlement instead of assuming the plan was revoked. That separates entitlement loss from usage-limit exhaustion and from transient API errors.

If the re-check confirms entitlement was revoked:

• Claude Code and Codex hooks surface a notice (via hook additionalContext) directing you to run sonar integrate to remove the analysis hooks, with a link to Sonar Agent Essentials. Hooks do not block the agent. The entitlement-loss notice is shown at most once every 24 hours per machine.
• sonar analyze agentic prints that Vortex analysis is not available for your organization, with a product link.

Re-run the integrate command interactively and decline to keep Vortex when prompted, to remove the hooks and related configuration.

If the re-check cannot determine the cause (for example, a transient API error), hooks skip silently and sonar analyze agentic prints a temporary-unavailability message.

When Vortex analysis consumption is reached

If your organization is entitled but has reached its Vortex analysis usage limit, sonar integrate still installs hooks and instructions and may print a warning that analysis will resume once usage resets. sonar analyze agentic and installed Vortex analysis hooks report that Vortex analysis is paused until usage resets. They do not suggest re-running sonar integrate, because your organization is still entitled. Re-running sonar integrate does not bypass the limit.

When Vortex context consumption is reached

If your organization is entitled but has reached its Vortex context consumption limit, sonar integrate still installs the skill and binary. Tool invocations through sonar context (or agent skills that call it) are blocked at runtime by the Vortex context daemon until usage resets or your quota increases. Re-running sonar integrate does not bypass the limit.

Recommended setup for a developer's laptop

sonar auth login
sonar integrate claude --global       # or copilot --global
sonar integrate git --global

This gives every project on the machine secrets blocking at three layers: AI agent reads, AI agent writes, and Git commits/pushes.

Recommended setup for a team rollout

For larger rollouts (dozens to thousands of engineers), pair the per-machine global integrations above with a CI-side scan that catches anything the local hooks missed:

sonar analyze secrets .
# Exits 51 if secrets are found, failing the pipeline.

See Environment variables and Exit codes for the CI/CD recipe.

Related pages

• Secrets detection

• Analyzing local changes

• Commands reference