> 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/integrations/cursor.md).

# Cursor

Install secrets-detection hooks, the SonarQube MCP Server, and Vortex analysis and Vortex context features for Cursor with the SonarQube CLI.

`sonar integrate cursor` configures the SonarQube CLI to work alongside [Cursor](https://cursor.com/). In an interactive terminal, the command prompts you to install each component:

* [Secrets detection](/sonarqube-cli/analysis/secrets-detection.md): 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](https://github.com/SonarSource/sonarqube-mcp-server), which lets Cursor fetch projects, issues, and rules directly.
* Vortex (when your connection has a Vortex subscription: SonarQube Cloud Team (annual) or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions): one prompt that installs Vortex analysis and Vortex context together. Accepting it adds:
  * [Vortex analysis](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) instructions as an always-applied rule in `~/.cursor/rules/` that tells Cursor to run `sonar analyze agentic` on your changes at the end of a turn
  * A `sessionStart` hook that injects [Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) when a session starts, letting Cursor use project guidelines, architecture, semantic navigation, and dependency context

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

## Prerequisites

* [The SonarQube CLI is installed and authenticated](/sonarqube-cli/quickstart-guide.md).
* [Cursor](https://cursor.com/) is installed.
* You're working inside a project directory, which lets the CLI auto-detect the SonarQube project for the preflight summary.

## Install

Install once for this machine:

```bash
sonar integrate cursor
```

The command writes hooks and config to `~/.cursor/` and applies to desktop Cursor sessions on this machine. See [Project versus global scope](/sonarqube-cli/integrations/integrations.md#project-versus-global-scope).

> **Warning:** Cursor's cloud and background agents only pick up project-level hooks, not global ones. Desktop Cursor sessions still run the installed hooks.

> **Note:** If a previous install wrote `.agents/skills/sonar-context-augmentation/SKILL.md`, update to SonarQube CLI 1.8.0 or later, then re-run `sonar integrate cursor` to replace that leftover skill with the session-start hook.

### What the command does

The integrator runs in three phases:

1. Discovery and validation. It locates your project's config using the [project key auto-detection](/sonarqube-cli/integrations/integrations.md#project-key-auto-detection) chain 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, and Vortex 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](/sonarqube-cli/integrations/integrations.md#install-confirmation) summary of accepted features. In interactive mode, press Enter to confirm. Then it installs accepted components into `~/.cursor/`.

   Common skip reasons include:

   * Your connection does not have a Vortex subscription (only available with SonarQube Cloud Team (annual) or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions).

### 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`, which blocks subsequent reads 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](/sonarqube-cli/analysis/secrets-detection.md#when-scanning-is-inactive).

### Options

| Option              | Description                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--non-interactive` | Non-interactive mode (no prompts).                                                                                                 |
| `--global`, `-g`    | Deprecated since 1.9.0. The install is already global; using the flag prints a warning and does not change the installation scope. |

### Where files are installed

| Location        | Hook and config location                |
| --------------- | --------------------------------------- |
| User home       | `~/.cursor/` (hooks, rules, MCP config) |
| Shared binaries | `~/.sonar/sonarqube-cli/bin/`           |

State for installed integrations is recorded in `~/.sonar/sonarqube-cli/state.json`. See [State and storage](/sonarqube-cli/administration/state-and-storage.md).

## Restart Cursor

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

## Vortex analysis and Vortex context

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 --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). The CLI auto-detects the project key: the rule omits `--project`. If analysis reports that no project is configured, the rule tells the agent to stay silent for the rest of the session instead of repeating a skip notice. Cursor's hook model does not support injecting analysis findings back into the conversation the way Claude Code and Codex hooks do. The CLI uses the same instructions-based pattern as GitHub Copilot CLI.

It also writes a `sessionStart` hook in `~/.cursor/hooks.json` that injects Vortex context when a Cursor session starts. If a previous install wrote `.agents/skills/sonar-context-augmentation/SKILL.md`, update to SonarQube CLI 1.8.0 or later, then re-run `sonar integrate cursor` to replace that leftover skill with the session-start hook.

For overviews of these features, see [Vortex analysis](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) and [Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md).

## Verify it works

### Test the secrets hook

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

   ```javascript
   // 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](/sonarqube-cli/administration/system-status.md).

### 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 does not, run `sonar auth status` to confirm the underlying token is healthy and restart Cursor.

### Test Vortex analysis

In Cursor, make a code change and end the turn. Cursor should run Vortex analysis on your changes per the installed rule. This requires a [Sonar Vortex](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) subscription.

## Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

```bash
sonar integrate cursor --non-interactive
```

In non-interactive mode the CLI does not prompt for feature selection, install confirmation, token repair, or feature removal; it installs every component that is not explicitly skipped. When you authenticate with [environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md), integrate commands also run in non-interactive mode even without the flag. Run [`sonar auth status`](/sonarqube-cli/using-sonarqube-cli/commands.md#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. Vortex is removed as one unit (Vortex analysis rule and session-start hook). See [integrations/README.md](/sonarqube-cli/integrations/integrations.md#removing-installed-features) for the full flow.

For a manual cleanup or non-interactive environments:

1. Delete the SonarQube hook files and rules written under `~/.cursor/`.
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](/sonarqube-cli/administration/uninstall.md) for the full removal procedure.

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

* [Secrets detection](/sonarqube-cli/analysis/secrets-detection.md)
* [Analyzing local changes](/sonarqube-cli/analysis/analyzing-local-changes.md)
* [Commands reference](/sonarqube-cli/using-sonarqube-cli/commands.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/integrations/cursor.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.