# Quickstart guide

> **Warning:** This product is in Beta stage and we may release breaking changes. The documentation here matches the release version listed in the table of contents.

This guide takes you from zero to a working CLI 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 integration](/sonarqube-cli/integrations/github-copilot.md)

## Step 1: Install the CLI

{% tabs %}
{% tab title="MACOS, LINUX" %}

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

{% tab title="WINDOWS (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.
{% endtab %}
{% endtabs %}

> **Note:** **Restart your terminal after installing.** The `sonar` command becomes available only after your shell reloads its `PATH`.

### Verify the install

```bash
sonar --version
```

You'll see a version number like `0.13.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 laptops):** a browser-based flow that creates and stores a user token in your system keychain.
* **Token-based (recommended for CI/CD and AI agents):** you supply an existing user token directly.

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

{% tabs %}
{% tab title="SONARQUBE CLOUD (EU)" %}

```bash
sonar auth login
```

SonarQube Cloud EU (`https://sonarcloud.io`) is the default. A browser window opens and walks you through token creation.
{% endtab %}

{% tab title="SONARQUBE CLOUD (US)" %}

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

See [Getting started in the US region](https://docs.sonarsource.com/sonarqube-cloud/getting-started/getting-started-in-us-region/) for details.
{% endtab %}

{% tab title="SONARQUBE SERVER" %}

```bash
sonar auth login --server <YourSonarQubeServerURL>
```

Replace `<YourSonarQubeServerURL>` with your instance URL (for example, `https://sonarqube.mycompany.com`).
{% endtab %}
{% endtabs %}

> **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 picks the first one your token can access. To target a specific organization, append `--org <YourOrganizationKey>`:

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

You can 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.

### Token-based login (non-interactive)

For automation, CI/CD, and AI agents, generate a user token in SonarQube and pass it directly:

```bash
sonar auth login --with-token <YourUserToken>
```

Combine with `--server` and `--org` as needed. For pipeline environments where you can't run `sonar auth login` at all, use [environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md) instead — they take precedence over saved 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";' > test-secret.js
sonar analyze secrets test-secret.js
```

The CLI flags the hardcoded token and exits with code `51`. Delete `test-secret.js` afterwards.

For deeper coverage — Git hooks, AI agent hooks, false positives — see [Secrets scanning](/sonarqube-cli/analysis/secrets-scanning.md).

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

```bash
sonar verify --staged
```

This sends your staged changes to SonarQube Cloud's [Agentic Analysis](https://docs.sonarsource.com/agent-centric-development-cycle/features/agentic-analysis) and reports new issues introduced in your change. 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](/sonarqube-cli/integrations/github-copilot.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. Restart your terminal (the installer updates your shell profile, but only new shells pick it up).
2. Confirm the binary exists:
   * macOS/Linux: `ls -l ~/.local/share/sonarqube-cli/bin/sonar`
   * Windows (PowerShell): `Get-Item $env:LOCALAPPDATA\sonarqube-cli\bin\sonar.exe`
3. If the binary is there but still not on your `PATH`, add it manually:
   * **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.

### 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 retry with `--with-token` instead.

### "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 against US (`https://sonarqube.us`).
* Re-run `sonar auth status` to inspect the active connection.

For more issues, see [Getting help](/sonarqube-cli/support/help.md).


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.