Cursor

Install secrets-detection hooks, the SonarQube MCP server, and Sonar Vortex's agentic analysis and context augmentation features for Cursor with the SonarQube CLI.

sonar integrate cursor configures the SonarQube CLI to work alongside Cursor. In an interactive terminal, the command prompts you to install each component:

• Secrets detection: a beforeSubmitPrompt hook that scans prompts before they're sent to the model, plus two file-read hooks (beforeReadFile and preToolUse) that scan files before Cursor reads them. Together they block any operation that would expose a secret.
• The SonarQube MCP Server so Cursor can fetch projects, issues, and rules directly.
• Sonar Vortex agentic analysis (SonarQube Cloud only, project-level installs, Team and Enterprise plans): an always-applied rule in .cursor/rules/ that tells Cursor to run sonar analyze agentic on your changes at the end of a turn.
• Sonar Vortex context augmentation (SonarQube Cloud only, project-level installs, Team and Enterprise plans) so Cursor can retrieve project guidelines, architecture, semantic navigation, and dependency context through the CLI integration.

Pass --non-interactive to accept every offered component without prompts (see Non-interactive install).

Prerequisites

• The SonarQube CLI is installed and authenticated.
• Cursor is installed.
• You're working inside a project directory (or you're installing globally with --global).

Install

Run inside the project you want to integrate, with the project key:

sonar integrate cursor --project <YourProjectKey>

Or install once for your whole machine:

sonar integrate cursor --global

Note: In an interactive terminal, if you omit both --global and --project, the CLI asks whether to install for this project or globally before continuing. See Project versus global scope.

Warning: --project and --global are mutually exclusive. Passing both causes the command to fail with an "invalid options" error (exit code 2).

Note: Cursor's cloud and background agents only pick up project-level hooks, not global ones. For full hook coverage on those agents, re-run without --global from a project directory.

Note: Agentic analysis is project-scoped. It's skipped when you run sonar integrate cursor --global; rerun the command without --global from a project directory to install agentic analysis instructions for that project.

Note: Context augmentation is project-scoped. It's skipped when you run sonar integrate cursor --global; rerun the command without --global from a project directory to install the context augmentation skill there.

To configure Cursor without context augmentation, pass --skip-context:

sonar integrate cursor --project <YourProjectKey> --skip-context

What the command does

The integrator runs in three phases:

1. Discovery and validation. It locates your project's config (sonar-project.properties, .sonarlint/connectedMode.json, the git origin remote when the repository is bound on SonarQube, or the explicit --project flag) and verifies the token.
2. Health check and repair. It calls SonarQube to confirm the token, organization, and project are valid. If the token is broken and you're running interactively, it offers to refresh it.
3. Installation. For each component (secrets hooks, MCP server, agentic analysis instructions, and context augmentation when eligible), the CLI either prompts you to install it, skips it with an explanation, or accepts it automatically in non-interactive mode. Before writing files, it shows a What will be installed summary of accepted features. In interactive mode, press Enter to confirm. Then it installs accepted components into either the project directory or your home directory, depending on --global.

   Common skip reasons include:

   • A global secrets hook is already configured (the project-level hook is skipped to avoid duplicate scans).
   • Agentic analysis isn't available on your connection (SonarQube Server), your organization isn't entitled, or you used --global (it's project-scoped).
   • Context augmentation isn't available for your organization (requires an eligible SonarQube Cloud plan), you passed --skip-context, or you used --global.

Secrets hooks

Cursor receives three secrets detection hooks in .cursor/hooks.json:

Hook event	Matcher	What it scans
beforeSubmitPrompt	UserPromptSubmit	The prompt you send to Cursor
beforeReadFile	Read|TabRead	Files before Cursor reads them from disk
preToolUse	Read	Files when the agent issues a Read tool call

The two file-read hooks work together as defense in depth. beforeReadFile intercepts disk reads, but files already open in the editor can bypass it. preToolUse covers agent Read tool calls at a different layer. When either hook detects a secret, Cursor blocks the read and the CLI appends the file to .cursorignore so subsequent reads are blocked natively.

If you're not authenticated or the sonar-secrets binary is missing, all three hooks fail closed and block the operation with a remediation message instead of silently allowing it through. See When scanning is inactive.

Options

Option	Description
--project, -p	SonarQube project key. Mutually exclusive with --global.
--global, -g	Install hooks and config globally in ~/.cursor instead of the project directory.
--non-interactive	Non-interactive mode (no prompts).
--skip-context	Skip the context augmentation skill install.

Where files are installed

Scope	Hook & config location
--global	~/.cursor/ (hooks, rules, MCP config)
Project (default)	Inside the repo's .cursor/ directory
Shared skill	.agents/skills/sonar-context-augmentation/SKILL.md (project) or ~/.agents/skills/ (global)
Shared binaries	~/.sonar/sonarqube-cli/bin/

State for installed integrations is recorded in ~/.sonar/sonarqube-cli/state.json. See State and storage.

Restart Cursor

Cursor reads its hook and MCP configuration at startup. Restart Cursor for the integration to take effect.

Sonar Vortex: agentic analysis and context augmentation features

When you run sonar integrate cursor against a SonarQube Cloud project, the command writes an always-applied rule in .cursor/rules/sonar-agentic-analysis.mdc that tells Cursor to run sonar analyze agentic --project <key> --depth DEEP on every file it modified that turn in a single command (repeat --file for each path, or fall back to the git change set). Cursor's hook model doesn't support injecting analysis findings back into the conversation the way Claude Code and Codex hooks do, so the CLI uses the same instructions-based pattern as GitHub Copilot CLI.

For overviews of these features, see Sonar Vortex agentic analysis and Sonar Vortex context augmentation.

Verify it works

Test the secrets hook

1. Create a file in your project with a fake-looking but secret-shaped value:

   // secrets.js
   const API_KEY = "sqp_1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13";

2. Ask Cursor to read it: "Read secrets.js."
3. Cursor should block the read and explain that the file contains a secret. The CLI also adds the file to .cursorignore.

After you've confirmed the hook is active, delete the test file.

Also run sonar system status to confirm the Cursor integration reports Secrets Hook: CONFIGURED. If the hook entry exists but the backing script is missing or malformed, status shows CONFIGURED / INVALID CONFIG and recommends re-running sonar integrate cursor. See Check system status.

Test the MCP server

In Cursor, ask: "Use the SonarQube MCP server to list my open projects." Cursor should call SonarQube and return your project list. If it doesn't, run sonar auth status to confirm the underlying token is healthy and restart Cursor.

Test agentic analysis (SonarQube Cloud only)

In Cursor, make a code change and end the turn. Cursor should run agentic analysis on your changes per the installed rule. This requires SonarQube Cloud and an agentic analysis entitlement for your organization.

Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

sonar integrate cursor --global --non-interactive

In non-interactive mode the CLI doesn't prompt for scope selection, feature selection, install confirmation, token repair, or feature removal; scope defaults to project when you omit --global, and it installs every component that isn't explicitly skipped. When you authenticate with environment variables, integrate commands also run in non-interactive mode even without the flag. Run sonar auth status afterward to confirm everything is configured correctly.

Uninstall

Run sonar integrate cursor again in an interactive terminal. For each installed feature, the CLI asks Keep? — answer No, confirm Proceed with removal?, and the CLI removes hooks, rules, and state for that feature. See integrations/README.md for the full flow.

For a manual cleanup or non-interactive environments:

1. Delete the SonarQube hook files and rules written under ~/.cursor/ (global) or .cursor/ (project).
2. Remove the SonarQube MCP server entry from your Cursor configuration.
3. Remove the integration entry from ~/.sonar/sonarqube-cli/state.json (under integrations.installed).

See Uninstalling for the full removal procedure.

Related pages

• Overview

• Secrets detection

• Analyzing local changes

• Commands reference