sonarsource/sonarqube-agent-plugins/sonar-list-issues

SonarQube — List Issues

Search for issues in a SonarQube project using the sonarqube-cli.

Unlike SonarQube MCP tools (which may use a default project from integration), `sonar list issues` always requires `-p <project-key>`. Resolve the key from the user-provided arguments or sonar-project.properties before running the CLI.

Usage

sonar-list-issues                                          # issues in the current project
sonar-list-issues my-project                               # issues in a specific project key
sonar-list-issues my-project --severities CRITICAL,BLOCKER # filter by severities
sonar-list-issues my-project --statuses OPEN,CONFIRMED     # filter by status
sonar-list-issues my-project --branch main                 # on a specific branch
sonar-list-issues my-project --pr 42                       # on a pull request

Prerequisites

This skill uses the sonarqube-cli command. The CLI must be installed and authenticated before proceeding.

Before proceeding, verify that sonar is available on your PATH and authenticated. If it is not, do not attempt to call any alternative commands or invent alternatives, and show the user:

Unable to list issues.

Possible causes:

- sonarqube-cli not installed or not authenticated — invoke the sonar-integrate skill

- Project key is wrong or missing — -p is mandatory for sonar list issues; invoke the sonar-list-projects skill or set sonar.projectKey in sonar-project.properties

Then ask the user (yes/no) whether to run the sonar-integrate skill now. Briefly explain what it does: it checks the SonarQube setup on their machine — installing or updating sonarqube-cli and verifying authentication — and re-configures the integration for this agent, including the SonarQube MCP server and secrets-scanning hooks. If they confirm, invoke the sonar-integrate skill yourself and follow it end-to-end in this session, then re-check and continue; if they decline, stop.

Instructions

Step 1: Resolve the project key

This flow uses `sonar list issues` (CLI), not MCP. The CLI always needs `-p <project-key>` — do not invoke it without a resolved key.

• If the user provided a project key, use it.
• Otherwise look for sonar.projectKey in sonar-project.properties at the repo root.
• If still not found, do not run sonar list issues. Tell the user: "Invoke the sonar-list-projects skill to find your project key, then re-run with that key," or add sonar.projectKey to sonar-project.properties. (MCP integration defaults do not apply to this CLI command.)

Step 2: Parse optional flags from the user-provided arguments

sonar list issues does not support filtering by issue type, rule, tag, or component, nor a --resolved flag. Only the options above (plus --format, --page, and --page-size) exist. To filter by rule/type/tag/component or to drill into a single file, use the MCP-based skills (e.g. sonar-analyze for a file, or mcp__sonarqube__search_sonar_issues_in_projects).

Step 3: Validate arguments

Before building the command, validate each user-supplied value against the following rules. If any value fails validation, stop and tell the user what was rejected and why — do not run the command. Validate the resolved project key (from args or sonar-project.properties) against the project-key pattern before running the CLI.

Step 4: Run sonar list issues

Build and run the command using a shell command. Always pass `-p` with the key resolved in Step 1.

sonar list issues -p <project-key> --format toon [--severities <values>] [--statuses <values>] [--branch <name>] [--pull-request <id>]

Only include optional flags that were provided.

Step 5: Format the results

If issues are found, present a summary line then a table sorted by severity then line number:

## SonarQube Issues — `my-project` (branch: `main`)
 
Found **12 issue(s)**:
 
| File                 | Line | Severity  | Rule         | Message                       |
| -------------------- | ---- | --------- | ------------ | ----------------------------- |
| src/auth/login.py    | 12   | 🔴 Blocker | python:S2077 | SQL injection risk            |
| src/utils/helpers.py | 34   | 🟠 High    | python:S2259 | Null dereference              |
| src/api/routes.py    | 67   | 🟡 Medium  | python:S3776 | Cognitive complexity too high |

Severity icons (the label depends on the server version):

• 🔴 Blocker
• 🟠 Critical / High
• 🟡 Major / Medium
• 🔵 Minor / Low
• ⚪ Info

If no issues are found:

## SonarQube Issues — `my-project`
 
✅ No issues found.

Step 6: Next steps

• To fix a specific issue: "Ask me to fix `<rule>` at `<file>:<line>`."
• To check the quality gate: "Invoke the sonar-quality-gate skill."