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

# Quickstart guide

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:

* [Authenticating in CI/CD with environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md)
* [Claude Code integration](/sonarqube-cli/integrations/claude-code.md)
* [GitHub Copilot CLI integration](/sonarqube-cli/integrations/github-copilot-cli.md)

## Step 1: Install the CLI

Choose your OS, then your installation method.

{% tabs %}
{% tab title="macOS, Linux" %}

### Homebrew

```bash
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](https://formulae.brew.sh/cask/sonarqube-cli).

### Mise

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

```bash
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.
{% endtab %}

{% tab title="Windows" %}

### Mise

```bash
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)

```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.
{% endtab %}
{% endtabs %}

### Verify the install

```bash
sonar --version
```

You'll see a version number like `0.14.0`. If you get `command not found`, see [Command not found after install](#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](/sonarqube-cli/using-sonarqube-cli/environment-variables.md).

> **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

```bash
sonar auth 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:

```bash
# SonarQube Server (self-hosted)
sonar auth login --server <YourSonarQubeServerURL>
# SonarQube Cloud (EU or US region)
sonar auth login --server "https://sonarcloud.io"
sonar auth login --server "https://sonarqube.us"
```

> **Warning:** **WSL users:** `sonar auth login` relies on system keychain access, which is not available in WSL. Authenticate with [environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md) 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>`:

```bash
sonar auth login --org my-org
```

Find your organization key on your SonarQube Cloud **Account** > **Organizations** page: [`https://sonarcloud.io/account/organizations`](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`:

```bash
export SONARQUBE_CLI_TOKEN=<YourUserToken>
export SONARQUBE_CLI_ORG=<YourOrganizationKey>
```

Check the [environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md) page for information about adding a SonarQube Server configuration, connecting to the US Cloud region, and detailing your credentials.

### Verify your connection

```bash
sonar auth status
```

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

```bash
sonar list 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

```bash
echo 'const API_KEY = "sqp_1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13";' > validate-secrets.js
sonar analyze secrets validate-secrets.js
```

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](/sonarqube-cli/analysis/secrets-detection.md).

### Analyze your local changes (SonarQube Cloud only)

```bash
sonar analyze --staged
```

This runs secrets scanning on your staged files and, on SonarQube Cloud, sends them to [Sonar Vortex agentic analysis](/agent-centric-development-cycle/verify/sonar-vortex-agentic-analysis.md). For more options (single files, branch comparison, JSON output), see [Analyzing local changes](/sonarqube-cli/analysis/analyzing-local-changes.md).

## What's next

* Wire the CLI into your AI coding workflow: [Claude Code](/sonarqube-cli/integrations/claude-code.md), [GitHub Copilot CLI](/sonarqube-cli/integrations/github-copilot-cli.md), [OpenAI Codex](/sonarqube-cli/integrations/codex.md).
* Block secrets at the Git layer: [Git hooks](/sonarqube-cli/integrations/git-hooks.md).
* Use the CLI in a pipeline: [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md), [Exit codes](/sonarqube-cli/using-sonarqube-cli/exit-codes.md).
* Browse the full [commands reference](/sonarqube-cli/using-sonarqube-cli/commands.md).

## 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 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`:
   * **macOS/Linux**: append this to your `~/.bashrc` or `~/.zshrc` and reload:

     ```bash
     export PATH="$HOME/.local/share/sonarqube-cli/bin:$PATH"
     ```
   * **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](/sonarqube-cli/using-sonarqube-cli/environment-variables.md) 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`).
* Re-run `sonar auth status` to inspect the active connection.

For more issues, see [Help](/sonarqube-cli/support/help.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-cli/quickstart-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.