/sonar-list-issues

name: sonar-list-issues
description: Search and filter SonarQube issues for a project, branch, or pull request via sonarqube-cli (`-p` is always required on the CLI; resolve the key from user arguments or sonar-project.properties)
argument-hint: "[project-key?] [--severities values] [--statuses values] [--branch name]"
allowed-tools: Read, Grep, Bash(sonar:*)

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

| Flag | Maps to CLI option | | ------------------------ | ------------------ | | `--severities <values>` | `--severities` | | `--statuses <values>` | `--statuses` | | `--branch <name>` | `--branch` | | `--pr <id>` | `--pull-request` |

> `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.

| Argument | Allowed pattern | | -------------- | ------------------------------------------------------------------------------------- | | project key | `^[a-zA-Z0-9_\-\.:]+$` | | `--severities` | comma-separated subset of: `INFO`, `MINOR`, `MAJOR`, `CRITICAL`, `BLOCKER`, `HIGH`, `MEDIUM`, `LOW` | | `--statuses` | comma-separated subset of: `OPEN`, `CONFIRMED`, `FALSE_POSITIVE`, `ACCEPTED`, `FIXED` | | `--branch` | `^[a-zA-Z0-9_\-\./]+$` | | `--pr` | digits only |

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
• 🔵 Mi