Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Developer

Quickstart guide

Install the SonarQube CLI, authenticate with SonarQube Cloud or SonarQube Server, and run your first three commands.

Install the CLI and run your first command in about five minutes. By the end, you'll have the CLI installed, an active SonarQube connection, and you'll have run a secrets scan and a local-change analysis.

If you're setting the CLI up for a CI/CD pipeline or an AI coding agent instead, follow these guides:

Note: This quickstart covers the SonarQube CLI (sonar), a developer tool for secrets scanning, local analysis, and AI agent integrations. If you want to run a full project analysis from a CI/CD pipeline, you want the SonarScanner CLI (sonar-scanner) instead. See the SonarScanner CLI docs for SonarQube Server or SonarQube Cloud.

Step 1: Install the CLI

Choose your OS, then your installation method.

Homebrew

brew install sonarqube-cli

Homebrew manages the binary location and PATH automatically. No terminal restart is needed. See the sonarqube-cli cask on Homebrew Formulae.

Mise

mise use -g sonarqube-cli@latest

This adds the CLI to your global Mise config and installs the latest release.

Note: Mise support for the SonarQube CLI was added in May 2026. If you get "sonarqube-cli not found in mise tool registry", update mise to version 2026.5 or later with mise self-update.

Install script

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

The installer places the sonar binary in ~/.local/share/sonarqube-cli/bin/ and appends that directory to your PATH in ~/.bashrc, ~/.zshrc, or your shell's profile file. Restart your terminal after running it.

Mise

mise use -g sonarqube-cli@latest

This adds the CLI to your global Mise config and installs the latest release.

Note: Mise support for the SonarQube CLI was added in May 2026. If you get "sonarqube-cli not found in mise tool registry", update mise to version 2026.5 or later with mise self-update.

Install script (PowerShell)

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

The installer places sonar.exe in %LOCALAPPDATA%\sonarqube-cli\bin\ and updates the user-level PATH environment variable. Open a new PowerShell window after running it.

Direct download

To install without a package manager, download the binary zip for your platform from the GitHub releases page. Extract the archive and add the directory containing sonar (or sonar.exe on Windows) to your PATH, then restart your terminal.

Verify the install

You'll see a version number like 0.14.0. If you get command not found, see Command not found after install at the bottom of this page.

Step 2: Authenticate

The CLI supports two authentication modes:

  • Interactive (recommended for personal use): the CLI opens your browser to log in to SonarQube, then stores the generated user token in your system keychain.

  • Environment variables (recommended for CI/CD and AI agents): the CLI reads SONARQUBE_CLI_TOKEN and related variables at runtime. No keychain or browser required. See Authenticating in CI/CD with environment variables.

Warning: User tokens are required when authenticating your SonarQube CLI with SonarQube Cloud or SonarQube Server. The CLI won't function properly if project tokens, global tokens, or scoped organization tokens are used during setup.

Interactive login

The CLI prompts you to choose between SonarQube Cloud and SonarQube Server, then asks for a region (Cloud) or an instance URL (Server). A browser window opens and walks you through token creation.

To skip these prompts, pass --server when you run the command:

Warning: WSL users: sonar auth login relies on system keychain access, which is not available in WSL. Authenticate with environment variables instead.

Specify an organization (SonarQube Cloud only)

SonarQube Cloud authentication is scoped to an organization. If you don't pass one, the CLI auto-selects the organization when you belong to exactly one, or prompts you to pick one when you belong to several. To skip the prompt, append --org <YourOrganizationKey>:

Find your organization key on your SonarQube Cloud Account > Organizations page: https://sonarcloud.io/account/organizations.

This option is ignored when authenticating with SonarQube Server.

Non-interactive authentication

For automation, CI/CD, and AI agents, set environment variables instead of running sonar auth login:

Check the environment variables page for information about adding a SonarQube Server configuration, connecting to the US Cloud region, and detailing your credentials.

Verify your connection

If the token is valid, you'll see the active server, organization (for Cloud), and the user it resolves to.

Step 3: Run your first three commands

Try these in order to confirm everything works end to end.

List your projects

Outputs every project your token can see as JSON. Pipe through jq if you need to transform or filter it.

Scan a file for secrets

The CLI flags the hardcoded token and exits with code 51. Delete validate-secrets.js afterwards.

For deeper coverage (Git hooks, AI agent hooks, false positives), see Secrets scanning.

Analyze your local changes

This runs secrets scanning on your staged files and, with an active subscription, sends them to Vortex analysis. For more options (single files, branch comparison, JSON output), see Analyzing local changes.

What's next

Troubleshooting

Command not found after install

If sonar --version returns command not found:

  1. Try restarting your terminal. This applies 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 configured for Mise. Mise requires a shell hook to activate. Follow the Mise getting started guide to set it up, then reopen your terminal.

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

    • macOS/Linux: append this to your ~/.bashrc or ~/.zshrc and reload:

    • Windows: open a new PowerShell window. If PATH still doesn't include the install directory, sign out and back in to reload your user environment.

  5. Verify the binary exists:

    • Install script on macOS/Linux: ls -l ~/.local/share/sonarqube-cli/bin/sonar

    • Install script on Windows (PowerShell): Get-Item $env:LOCALAPPDATA\sonarqube-cli\bin\sonar.exe

Browser login doesn't return to the terminal

sonar auth login opens a local callback URL that the browser redirects to after you approve the token. If the browser hangs:

  • Make sure no firewall is blocking 127.0.0.1 on the printed port.

  • Cancel the prompt (Ctrl+C) and use your environment variables to authenticate without a browser.

"Invalid token" or "Authentication failed"

  • Confirm you're using a user token, not a project, global, or organization-scoped token.

  • For SonarQube Cloud, check that the token belongs to the correct region. EU (https://sonarcloud.io) tokens do not work with servers in the US region (https://sonarqube.us).

  • Run sonar auth status to check which server URL and organization the CLI is using. If it shows the wrong server or organization, run sonar auth login again to set up the correct connection.

For more issues, see Help.

PreviousSonarQube CLI
NextCommands reference

Last updated

Was this helpful?