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

# Pi

Secrets-detection extensions, the SonarQube MCP Server, and Sonar Vortex analysis and Vortex context for Pi, installed with the SonarQube CLI.

`sonar integrate pi` configures the SonarQube CLI to work alongside [Pi](https://pi.dev/). In an interactive terminal, the command shows these recommended components, then asks you to install them or customize the selection (see [Install confirmation](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#install-confirmation)):

* **A secrets-detection extension** that blocks a `read` when the file contains a secret, and masks secrets in a message before the message is sent
* **The** [**SonarQube MCP Server**](https://docs.sonarsource.com/sonarqube-mcp-server/), which lets Pi 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): installs Vortex analysis and Vortex context together. It adds:
  * A [Vortex analysis](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) extension that runs fast `STANDARD` analysis after each `edit` or `write`. The edit is not blocked.
  * An end-of-turn reminder that tells Pi to run `DEEP` analysis on the files it changed
  * A session-start extension that injects [Vortex context](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) once per session

Choose Pi from the bare `sonar integrate` menu, or run `sonar integrate pi` directly. When `~/.pi/agent` exists, that menu lists Pi with the other detected agents.

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](https://docs.sonarsource.com/sonarqube-cli/quickstart-guide.md).
* [Pi](https://pi.dev/) 0.99.0 or newer is installed. Earlier versions ignore `~/.pi/agent/mcp.json` and do not load the SonarQube MCP Server. `sonar integrate pi` does not check the Pi version and does not warn you.
* `sonar` is on the `PATH` that Pi uses.

## Install

Install once for this machine:

```bash
sonar integrate pi
```

The command writes extensions and MCP configuration under `~/.pi/agent/`. That path is your user home on every platform, including Windows. It applies to every Pi session on this machine. See [Project versus global scope](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#project-versus-global-scope).

### What the command does

The integrator runs in two phases:

1. Validation. It checks that your saved token can reach SonarQube. On SonarQube Cloud, your connection must include an organization. An invalid token stops setup and tells you to run `sonar auth login`. An unreachable server stops setup and asks you to check the server URL and your network connection.
2. Installation. The CLI shows a [What will be installed](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#install-confirmation) summary of the recommended components (secrets detection, MCP server, and Vortex when eligible). In an interactive terminal, choose **Install recommended** to write that set, or **Customize** to accept or decline each component and then press Enter. Components that are not available are skipped with an explanation. In non-interactive mode, every eligible component is installed without prompts. The CLI then writes the accepted components under `~/.pi/agent/`.

   A common skip reason is that 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 extension

The extension is `~/.pi/agent/extensions/sonar-secrets.ts`. Pi loads every `.ts` file in that directory. Do not edit the file by hand. Re-run `sonar integrate pi` to refresh it.

| Pi event     | What it does                                                                                                                                                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read`       | Scans the file before Pi reads it. A secret blocks the read and tells Pi not to open it another way. If Pi needs to inspect other files, scan specific files with `sonar analyze secrets <files>` instead of scanning a whole tree with `.` or the repository root. |
| User message | Scans the message before it is sent. Secrets that can be masked are replaced, and the message is still sent.                                                                                                                                                        |

The extension fails closed when you are not authenticated, the secrets analyzer is missing, the scan fails, or `sonar` is missing from `PATH`. A file read is blocked. A message that cannot be checked, or that contains a secret the extension cannot mask, is replaced with a notice that starts with `[SonarQube] Message blocked:` and is not sent as written. The notice says the original content was not sent and asks Pi to tell you that SonarQube blocked the message. A tool other than `read` is not scanned. A message with no secrets is left unchanged. Upgrade the CLI, or run `sonar integrate pi` again, so an existing extension uses this notice.

### Vortex analysis and Vortex context

When you accept Vortex, `sonar integrate pi` installs two more extensions under `~/.pi/agent/extensions/`. Do not edit them by hand.

* `sonar-sqaa.ts` runs after `edit` and `write`. It analyzes that file at `STANDARD` depth (see the `--depth` option of [`sonar analyze agentic`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-analyze-agentic)) and appends findings to the tool output. Pi is told to report those findings and to say they come from Sonar Vortex analysis. The extension never blocks the edit. A missing project, a scan error, or `sonar` missing from `PATH` stays silent. On HTTP 403, Pi can show the same unavailable notice as the other Vortex analysis hooks. See [integrations/README.md](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#when-vortex-is-no-longer-available).
* Before a completed turn ends, the same extension asks Pi to run one `DEEP` command for the files it changed, then continue:

  ```bash
  sonar analyze agentic --depth DEEP --file 'src/app.ts'
  ```

  Repeat `--file` for each path. Paths are relative to the session directory. The reminder is not shown in the terminal, and it is sent at most once per prompt. An interrupted run does not add it. The reminder omits `--project` and `--branch` because the CLI auto-detects the current git branch and analyzes each file against the project that owns it. In a repository with several projects, run that command from a directory that contains every changed file, usually the repository root. The edit hook does the same for the edited file and stays silent when no project of the active connection owns it. Pi does not receive an `AGENTS.md` protocol snippet. See [Files and the project root](https://docs.sonarsource.com/sonarqube-cli/analysis/analyzing-local-changes.md#files-and-the-project-root).
* `sonar-cag.ts` runs when a session starts. It injects Vortex context so Pi can use project guidelines, architecture, semantic navigation, and dependency context. The announcement is not shown as its own line in the terminal. A continued session (`pi --continue`) or `/reload` does not add a second announcement. When context cannot load, Pi shows the warning in the session once. See [When Vortex context does not load](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#when-vortex-context-does-not-load). If the check takes longer than 20 seconds, Pi continues without the announcement.

The CLI installs the Vortex context binary under `~/.sonar/sonarqube-cli/bin/`. After that, `sonar context` forwards to the binary.

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

### MCP server

The command adds a `sonarqube` entry under `mcpServers` in `~/.pi/agent/mcp.json`:

```json
{
  "mcpServers": {
    "sonarqube": {
      "command": "sonar",
      "args": ["run", "mcp"]
    }
  }
}
```

Pi starts that local command. The file does not include a project key. `sonar run mcp` resolves the project when it runs. Other MCP servers in the file are kept. Removing the feature removes only the `sonarqube` entry.

When [`SONAR_USER_HOME`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md#cli-home-directory) is set before you run the command, the entry also includes an `env` object with that path.

### 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        | What is written                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------ |
| User home       | `~/.pi/agent/extensions/sonar-secrets.ts`, and, when Vortex is installed, `sonar-sqaa.ts` and `sonar-cag.ts` |
| MCP server      | `~/.pi/agent/mcp.json`                                                                                       |
| Shared binaries | `~/.sonar/sonarqube-cli/bin/` (the secrets analyzer, and the Vortex context binary when Vortex is installed) |

State for the integration is recorded in `~/.sonar/sonarqube-cli/state.json`. See [State and storage](https://docs.sonarsource.com/sonarqube-cli/administration/state-and-storage.md).

## Restart Pi

Pi loads extensions and MCP configuration when it starts. Restart Pi after you install or remove them.

## Verify it works

### Test a file read

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 Pi to read it: *"Read secrets.js."*
3. Pi should block the read and explain that the file contains a secret.

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

### Test a message

Send Pi a message that includes the same kind of fake token. Pi should not send the secret as written. When the scanner can mask it, the message is still sent with the secret replaced. When Pi blocks the message, the text starts with `[SonarQube] Message blocked:`.

### Test the MCP server

Ask Pi to list your SonarQube projects through the MCP server. If the call fails, run `sonar auth status` to confirm the token is healthy and restart Pi.

`sonar system status` lists the Pi integration and reports MCP server status for `~/.pi/agent/mcp.json`. When the MCP entry is invalid, status recommends `sonar integrate pi`. See [Check system status](https://docs.sonarsource.com/sonarqube-cli/administration/system-status.md).

### Test Vortex analysis

Make a code change through Pi (for example, ask it to edit a file). After the edit, Pi should receive the analysis. Before ending the turn, it should run `DEEP` analysis on the modified files. This requires a [Sonar Vortex analysis](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) subscription.

### Test Vortex context

After you accept Vortex, start a Pi session in a linked project. Pi should receive Vortex context at session start. The announcement is not shown as its own line in the terminal. Continue that session, or run `/reload`, and Pi should not receive a second announcement. This requires a [Sonar Vortex context](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) subscription.

## Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

```bash
sonar integrate pi --non-interactive
```

In non-interactive mode, the CLI does not prompt for feature selection, install confirmation, token repair, or feature removal. When you authenticate with [environment variables](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md), integrate commands also run in non-interactive mode even without the flag. Every component that is not explicitly skipped is installed automatically, including Vortex when your connection has a Vortex subscription. Run [`sonar auth status`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-auth-status) afterward to confirm everything is configured correctly.

## Uninstall

Run `sonar integrate pi` again in an interactive terminal and choose **Customize**. For each installed feature, the CLI asks **Keep?**: answer No, confirm **Proceed with removal?**, and the CLI removes that feature and its state. Remove the secrets extension, Vortex, and the MCP server separately. Vortex is removed as one unit (the analysis extension and the session-start extension). See [integrations/README.md](https://docs.sonarsource.com/sonarqube-cli/integrations/integrations.md#removing-installed-features) for the full flow.

For a manual cleanup or non-interactive environments:

1. Delete `~/.pi/agent/extensions/sonar-secrets.ts`. If Vortex was installed, also delete `~/.pi/agent/extensions/sonar-sqaa.ts` and `~/.pi/agent/extensions/sonar-cag.ts`. Leave other extensions in that directory.
2. Remove the `sonarqube` entry under `mcpServers` in `~/.pi/agent/mcp.json`. Leave other MCP servers in place.
3. Remove the Pi entry from `~/.sonar/sonarqube-cli/state.json` (under `integrations.installed`).

See [Uninstalling](https://docs.sonarsource.com/sonarqube-cli/administration/uninstall.md) for the full removal procedure.

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

* [Secrets detection](https://docs.sonarsource.com/sonarqube-cli/analysis/secrets-detection.md)
* [Analyzing local changes](https://docs.sonarsource.com/sonarqube-cli/analysis/analyzing-local-changes.md)
* [Commands reference](https://docs.sonarsource.com/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/pi.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.
