SonarQube CLI

Catch code quality and security issues in your terminal—before they reach production.

The SonarQube CLI integrates enterprise-grade static analysis into your development workflow:

• 🔒 Secret Detection — Scan code for hardcoded credentials and prevent secrets from being sent to LLM providers
• ⚡ Fast Feedback Loop — Get server-side issue detection on your local changes without waiting for CI/CD
• 🤖 AI-Assisted Fixes — Generate remediation suggestions for security vulnerabilities (SonarQube Cloud)
• 🔗 Agent Integration — Seamless hooks for Claude Code, GitHub Copilot CLI, Codex, Cursor, Antigravity, OpenCode, Devin, and Pi
• 📊 Scriptable — Query and manage SonarQube issues programmatically with JSON output

Use it standalone or integrate with: Git hooks, Claude Code, GitHub Copilot CLI, Codex, Cursor, Antigravity, OpenCode, Devin, Pi, CI/CD pipelines, custom automation

🤖 For AI Agents: If you are an AI agent reading this, navigate to docs/llms.txt for machine-readable command documentation optimized for LLM consumption.

We are actively collecting feedback on this product. Please share your thoughts via this form!

Documentation

• 📘 Official Documentation: docs.sonarsource.com/sonarqube-cli
• 🌐 Project Website: sonarsource.com/sonarqube/cli
• 📖 Command Reference: sonarsource.com/sonarqube/cli/commands.html

Table of Contents

• Documentation
• Three Ways to Use This CLI
• Prerequisites
• Quick Start
  • Step 1: Install
  • Step 2: Authenticate
  • Step 3: Try Basic Commands
  • Step 4: Analyze Local Changes
• Integrations
  • Claude Code Integration
  • Git Hooks
  • GitHub Copilot CLI Integration
• Example Outputs
• Troubleshooting

Three Ways to Use This CLI

The SonarQube CLI is designed for three distinct use cases:

1. 🤖 Agentic Use — Built-in support for AI coding agents (Claude Code, GitHub Copilot CLI, Codex, Cursor, Antigravity, OpenCode, Devin, and Pi) with safeguards that prevent secrets from being sent to LLM providers

   sonar integrate claude
   # Now Claude Code will automatically scan for secrets before processing your code
   

2. 🖥️ Interactive CLI — Run commands directly in your terminal to scan code, check issues, and manage SonarQube projects manually

   sonar list issues --project my-app
   sonar analyze --file file.ext
   

3. ⚙️ Scripting & Automation — Integrate into scripts for reporting, dashboards, or automated quality gates

   # Generate a report of issues across all projects:
   sonar list projects | jq -r '.projects[].key' | while read project; do
     echo "Project: $project"
     sonar list issues --project "$project" | jq -r '.issues[].severity' | sort | uniq -c
   done
   

Prerequisites

Before installing, you need:

• SonarQube Access (choose one):

  • SonarQube Cloud — Free for open source projects, paid for private repositories
  • SonarQube Server — Self-hosted instance (v2025.1+)

• Operating System: Linux (x86-64, ARM64), macOS (ARM64), or Windows (x86-64)

Optional:

• Git 2.x+ for git hook integrations
• Claude Code, GitHub Copilot CLI, Codex, Cursor, Antigravity, OpenCode, Devin, or Pi for AI assistant integrations

First time with SonarQube? Create a free SonarQube Cloud account — no credit card required for open source projects.

Quick Start

Step 1: Install

Choose the install channel that fits your setup:

Homebrew (macOS/Linux):

brew install sonarqube-cli

Mise (macOS, Linux, or Windows):

mise use -g sonarqube-cli@latest

Install script (Linux/macOS):

curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh | bash

Install script (Windows, from PowerShell):

irm https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.ps1 | iex

Verify installation:

sonar --version
# Example output: 1.0.0

Note: Restart your terminal after using the install scripts so your updated PATH is reloaded. Homebrew manages PATH automatically, and Mise assumes its shell activation is already configured.

Step 2: Authenticate

Connect to SonarQube Cloud EU (default):

sonar auth login
# Opens your browser to sign in to SonarQube and generates a user token
# Returns to terminal when complete

For SonarQube Cloud US:

sonar auth login --server https://sonarqube.us

For self-hosted SonarQube Server:

sonar auth login --server https://sonarqube.mycompany.com

Verify authentication:

sonar auth status
# Verifying token......
# [✓ Connected]
# Server  https://sonarcloud.io
# Org     my-org
# Source  OS Keychain

For automation, CI/CD, and AI agents, pass the token via environment variables. The CLI reads them at command time, so nothing is written to disk or the OS keychain.

Generate a token first: SonarQube → My Account → Security → Generate Token.

Then define the following environment variables before invoking sonar (use your runner's secret store in CI, or your preferred local mechanism — direnv, an untracked .env file, a password manager CLI, etc.):

• SonarQube Cloud: SONARQUBE_CLI_TOKEN + SONARQUBE_CLI_ORG
• Self-hosted SonarQube Server: SONARQUBE_CLI_TOKEN + SONARQUBE_CLI_SERVER

With those exported, any command works without further configuration:

sonar list projects

Set both variables — if only SONARQUBE_CLI_TOKEN is present, the CLI prints a warning on stderr and falls back to keychain credentials, which is rarely what automation wants. Never commit the token or pass it as a CLI argument.

Step 3: Try Basic Commands

List your projects:

sonar list projects
# {"projects":[{"key":"my-org_my-app","name":"my-app"},
#              {"key":"my-org_demo","name":"demo-project"}],
#  "paging":{"pageIndex":1,"pageSize":500,"total":2,"hasNextPage":false}}

Output is JSON by default. Pipe through jq for ad-hoc filtering, e.g. sonar list projects | jq -r '.projects[].key'.

Scan a file for secrets:

cat > test.js <<'EOF'
const STRIPE_KEY = "sk_live_<PASTE_A_REAL_STRIPE_KEY_HERE>";
EOF
sonar analyze secrets test.js
# Sonar Secrets CLI - BETA (2.43.0.11106)
# Trying to authenticate to SonarQube Server or Cloud, in order to enable complete functionality
# Authentication successful
# Running analysis...
# Found 1 secret
# Stripe API Key
# File: test.js
# Location: [1:21-1:53]
# Secret: sk_*****************************
# ❌ Secrets found (227ms)
# 💡 Remove the reported secret, then rerun the scan.

When a secret is found, the command exits with code 51.

Check issues in a project:

sonar list issues --project my-org_my-app --format table --page-size 3
# SEVERITY | RULE             | MESSAGE                                                 | FILE
# ---------------------------------------------------------------------------------------------------------------
# CRITICAL | typescript:S3776 | Refactor this function to reduce its Cognitive Complexity | src/preview.tsx:17
# CRITICAL | typescript:S2004 | Refactor this code to not nest functions more than 4...   | src/Preview.tsx:235
# CRITICAL | typescript:S3776 | Refactor this function to reduce its Cognitive Complexity | src/Description.tsx:43

Supported formats: json (default), table, toon, csv.

💡 Tip: The --project flag is often optional—if your working directory contains a sonar-project.properties file or a SonarLint connected-mode binding under .sonarlint/, the CLI picks the project key up from there.

Step 4: Analyze Local Changes (SonarQube Cloud only)

cd your-project-directory
sonar analyze --file file.ext
# Analyzes uncommitted changes for new issues
# Only shows issues YOU introduced in your changes

Common options:

sonar analyze --file src/myfile.ts          # Analyze a specific file
sonar analyze --base main                   # Analyze changes vs main branch
sonar analyze --branch feature-xyz          # Set branch context

---

Integrations

Claude Code Integration

Hooks apply to all Claude Code sessions on this machine:

sonar auth login
sonar integrate claude

This installs:

• Pre-tool-use hook for secrets scanning — Prevents hardcoded credentials from being sent to LLM providers
• SonarQube Agentic Analysis integration — Server-side code quality analysis in your workflow
• Model Context Protocol (MCP) server — Access SonarQube data directly from Claude Code

Git Hooks

Hooks apply to all repositories on this machine:

Pre-commit hook (scan staged files before each commit):

sonar integrate git --hook pre-commit

Pre-push hook (scan committed files before each push):

sonar integrate git --hook pre-push

For CI/CD or automation (non-interactive mode):

sonar integrate git --hook pre-commit --non-interactive
# Skips all prompts, fails fast on errors

GitHub Copilot CLI Integration

Hooks apply to all Copilot CLI sessions on this machine:

sonar auth login
sonar integrate copilot

This installs:

• Pre-tool-use hook for secrets scanning — Prevents hardcoded credentials from being sent to LLM providers
• SonarQube Agentic Analysis integration — Server-side code quality analysis in your workflow
• Model Context Protocol (MCP) server — Access SonarQube data directly from Copilot

Example Outputs

Scanning for Secrets

$ sonar analyze secrets src/config.ts
  sonar-secrets 2.43.0.11106 is already installed (latest)
Sonar Secrets CLI - BETA (2.43.0.11106)
Trying to authenticate to SonarQube Server or Cloud, in order to enable complete functionality
Authentication successful
Running analysis...
Found 1 secret
Stripe API Key
File: src/config.ts
Location: [5:20-5:52]
Secret: sk_*****************************
❌ Secrets found (227ms)
💡 Remove the reported secret, then rerun the scan.

Exit codes: 0 when no secrets are found, 51 when at least one is found.

Listing Issues

sonar list issues emits JSON by default; pass --format table for the human-readable view shown below.

$ sonar list issues --project my-org_my-app --severities CRITICAL,BLOCKER --page-size 3 --format table
SEVERITY | RULE             | MESSAGE                                                                              | FILE
-------------------------------------------------------------------------------------------------------------------------
CRITICAL | typescript:S3776 | Refactor this function to reduce its Cognitive Complexity from 26 to the 15 allowed. | code/addons/a11y/src/preview.tsx:17
CRITICAL | typescript:S2004 | Refactor this code to not nest functions more than 4 levels deep.                    | code/addons/docs/src/blocks/components/Preview.tsx:235
CRITICAL | typescript:S3776 | Refactor this function to reduce its Cognitive Complexity from 23 to the 15 allowed. | code/addons/vitest/src/components/Description.tsx:43

Analyzing Local Changes

$ sonar analyze
SonarQube Agentic Analysis: no files in the change set to analyze.

When there are staged changes against a project configured for SonarQube Cloud Agentic Analysis, the analyzer reports new issues introduced by the change set in the same text/ json format selectable via --format.

LLM-Optimized Output Format

For AI coding assistants, use --format toon — a token-efficient, YAML-flavored encoding of the same JSON payload:

$ sonar list issues --project my-org_my-app --severities BLOCKER --page-size 1 --format toon
total: 88
p: 1
ps: 1
paging:
  pageIndex: 1
  pageSize: 1
  total: 88
issues[1]:
  - key: AZ0avojpNWh-T1cKsujg
    rule: "typescript:S3516"
    severity: BLOCKER
    component: "my-org_my-app:src/ConfigFile.ts"
    project: my-org_my-app
    line: 377
    message: "Refactor this function to not always return the same value."
    type: CODE_SMELL

This format is designed for parsing by LLMs and can be used with Claude Code, GitHub Copilot CLI, Codex, Cursor, Antigravity, OpenCode, Devin, Pi, or custom AI workflows.

Troubleshooting

"Project key not found"

Symptom: Error: Project 'my-project' not found

Cause: Using the project display name instead of the project key.

Solution: Use the exact project key from the JSON output of sonar list projects:

# Find the correct key:
sonar list projects -q my-project
# {"projects":[{"key":"my-org_my-project","name":"my-project"}],
#  "paging":{"pageIndex":1,"pageSize":500,"total":1,"hasNextPage":false}}

# Or, for just the keys:
sonar list projects -q my-project | jq -r '.projects[].key'

# Use the key value (not the name) for subsequent commands:
sonar list issues --project my-org_my-project

---

"No issues found" but issues exist in SonarQube web UI

Cause: Project hasn't been scanned yet, or you're checking the wrong branch.

Solution:

1. Verify your project has at least one completed scan in SonarQube
2. Check you're authenticated to the right organization:

   sonar auth status
   

3. For branch-specific issues, specify the branch:

   sonar list issues --project my-org_my-app --branch feature-xyz
   

---

"Authentication failed" or token errors

Symptom: Error: Invalid token or browser authentication fails

Solution: Use token-based authentication:

1. Go to SonarQube → My Account → Security → Generate Token
2. Copy the generated token
3. Use following environment variables (set them globally before running commands from a new terminal):

   SONARQUBE_CLI_TOKEN=YOUR_TOKEN
   SONARQUBE_CLI_SERVER=https://sonarcloud.io  # or your SonarQube Server URL
   SONARQUBE_CLI_ORG=your-org-key              # SonarQube Cloud only
   

For SonarQube Cloud, ensure you're using the correct region:

• EU: https://sonarcloud.io
• US: https://sonarqube.us

---

sonar analyze says "Not a git repository"

Cause: sonar analyze requires git to detect changes.

Solution:

• Run from inside a git repository:

  cd your-project
  sonar analyze
  

• Or analyze a specific file instead:

  sonar analyze --file src/myfile.ts
  

---

Git hook doesn't run after installation

Symptom: Installed pre-commit hook but it doesn't execute on git commit

Solution:

1. Check the hook file exists and is executable:

   ls -la .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit
   

2. Test the hook manually:

   .git/hooks/pre-commit
   

3. For global hooks, verify git configuration:

   git config --global core.hooksPath
   # Should show: ~/.sonar/git-hooks (or similar)
   

---

"Command not found: sonar" after installation

Symptom: After installing, terminal doesn't recognize sonar

Solution:

1. Restart your terminal if you used the install script, or if you just changed your shell setup.

2. If you installed with Homebrew, make sure Homebrew itself is already on your PATH, then retry brew install sonarqube-cli.

3. If you installed with Mise, make sure your shell is already configured for Mise and reopen your terminal.

4. If you used the install script and it still doesn't work, manually add it to PATH:

   Linux/macOS — Add to ~/.bashrc or ~/.zshrc:

   export PATH="$HOME/.local/share/sonarqube-cli/bin:$PATH"
   

   Then reload: source ~/.bashrc (or ~/.zshrc)

   Windows — The installer should have updated PATH automatically. Try:

   • Open a new PowerShell window
   • Restart your computer if the issue persists

5. Verify the binary exists:

   # Install script on Linux/macOS:
   ls -la ~/.local/share/sonarqube-cli/bin/sonar
   
   # Install script on Windows (PowerShell):
   ls $env:LOCALAPPDATA\sonarqube-cli\bin\sonar.exe
   

---

Secrets scanning shows false positives

Symptom: sonar analyze secrets flags test data or example code

Solution:

Secrets scanning is intentionally sensitive to avoid missing real credentials. For test files:

1. Use obviously fake values:

   // ✅ Won't be flagged:
   const API_KEY = 'test_fake_key_for_unit_tests';
   const TOKEN = 'dummy-token-12345';
   
   // ❌ Might be flagged:
   const API_KEY = 'sk_live_abc123xyz789';
   

2. Store test secrets in ignored files:

• .env.test files are often excluded by default
• Keep real-looking test data in fixture files outside src/

3. For legitimate exceptions: Consider adding comments explaining why the value is safe, or use environment variables even in tests.

---

Still having issues?

• Search existing issues: GitHub Issues
• Open a new issue: New Issue

Include in your report:

• Output of sonar --version
• Full error message (with sensitive info redacted)
• Command you ran
• Operating system and version
• For authentication issues: Server URL (SonarQube Cloud vs Server)

State Management

See State Management for more information.

Uninstalling

Homebrew

brew uninstall sonarqube-cli

Mise

mise use -g --remove sonarqube-cli
mise uninstall --all sonarqube-cli

Install script (Linux/macOS)

1. Delete the ~/.local/share/sonarqube-cli/ folder.
2. Remove export PATH="$HOME/.local/share/sonarqube-cli/bin:$PATH" from your ~/.bashrc or ~/.zshrc files.

Install script (Windows)

1. Delete the %localappdata%\sonarqube-cli\ folder.
2. Remove this folder from the PATH user-level environment variable.

Data collection

The SonarQube CLI collects anonymous usage data and error reports to help improve the product.

Telemetry: Anonymous command usage statistics are sent to SonarSource. See telemetry-sample.md for a sample of the data that is collected.

Error reporting: Unhandled exceptions are reported to Sentry to help us identify and fix crashes.

Both are enabled by default and share the same opt-out toggle. To disable all data collection:

sonar config set telemetry.enabled false

You can also set the DO_NOT_TRACK=1 environment variable to disable telemetry for a session without changing persisted configuration.

No personally identifiable information is transmitted.

Contributing

We don't accept external pull requests on this project. This isn't about the quality of your change — keeping all changes in one place lets us properly track, plan, prioritize, and test everything that goes into the CLI.

That doesn't mean we don't want to hear from you — we do. If you've hit a bug or have an idea, please open a GitHub Issue and we'll take it from there.

The source is public, so you're welcome to fork it, read it, and experiment. See CONTRIBUTING.md if you'd like to build the CLI from source.

License

Copyright SonarSource Sàrl.

SonarQube CLI is released under the GNU Lesser General Public License, Version 3.0⁠,.