# Environment variables

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

Use environment variables to configure the SonarQube CLI without running `sonar auth login`—the recommended approach for CI/CD pipelines, container images, AI agent runners, and other headless environments.

> **Warning:** **WSL users:** `sonar auth login` relies on system keychain access, which is not available in WSL. Use the variables below to authenticate instead.

## Authentication

Set these variables to supply credentials directly. When the CLI finds a valid combination, it uses them immediately and ignores any saved connection from `sonar auth login`.

| Variable               | Description                                                                                                                                                                                                                                      | Default                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| `SONARQUBE_CLI_TOKEN`  | Your user token. Required for environment variable authentication.                                                                                                                                                                               | -                                                         |
| `SONARQUBE_CLI_ORG`    | Your SonarQube Cloud organization key. Use together with `SONARQUBE_CLI_TOKEN` to authenticate with SonarQube Cloud.                                                                                                                             | -                                                         |
| `SONARQUBE_CLI_SERVER` | Your server URL. Use together with `SONARQUBE_CLI_TOKEN` to authenticate with SonarQube Server. For SonarQube Cloud, use together with `SONARQUBE_CLI_ORG` and set to `https://sonarcloud.io` (EU region) or `https://sonarqube.us` (US region). | `https://sonarcloud.io` (when `SONARQUBE_CLI_ORG` is set) |

`SONARQUBE_CLI_TOKEN` must be paired with either `SONARQUBE_CLI_ORG` or `SONARQUBE_CLI_SERVER` — or both — to connect:

* **SonarQube Cloud, EU region:** `SONARQUBE_CLI_TOKEN` + `SONARQUBE_CLI_ORG`. `SONARQUBE_CLI_SERVER` defaults to `https://sonarcloud.io`.
* **SonarQube Cloud, US region:** `SONARQUBE_CLI_TOKEN` + `SONARQUBE_CLI_ORG` + `SONARQUBE_CLI_SERVER=https://sonarqube.us`.
* **SonarQube Server:** `SONARQUBE_CLI_TOKEN` + `SONARQUBE_CLI_SERVER`.

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

### Precedence

When the CLI resolves credentials, it applies the following order:

1. **Environment variables**, if a valid combination is set, win over everything else.
2. **Saved connection from `sonar auth login`** (token from the system keychain) is used otherwise.
3. If neither is available, the command fails with an authentication error.

If `SONARQUBE_CLI_TOKEN` is set but its required pair (`SONARQUBE_CLI_ORG` or `SONARQUBE_CLI_SERVER`) is missing, the CLI prints a warning and falls back to step 2.

> **Note:** These variable names (`SONARQUBE_CLI_*`) are specific to the SonarQube CLI. The [SonarQube MCP Server](https://github.com/SonarSource/sonarqube-mcp-server) uses a different set (`SONARQUBE_TOKEN`, `SONARQUBE_URL`, `SONARQUBE_ORG`). They do not interfere with each other.

## Examples

### Authenticate in a shell

{% tabs %}
{% tab title="MACOS, LINUX (BASH/ZSH)" %}
SonarQube Cloud, EU region:

```bash
export SONARQUBE_CLI_TOKEN=<YourUserToken>
export SONARQUBE_CLI_ORG=<YourOrganizationKey>
sonar list issues -p <YourProjectKey>
```

SonarQube Cloud, US region:

```bash
export SONARQUBE_CLI_TOKEN=<YourUserToken>
export SONARQUBE_CLI_ORG=<YourOrganizationKey>
export SONARQUBE_CLI_SERVER=https://sonarqube.us
sonar list issues -p <YourProjectKey>
```

SonarQube Server:

```bash
export SONARQUBE_CLI_TOKEN=<YourUserToken>
export SONARQUBE_CLI_SERVER=<YourSonarQubeServerURL>
sonar list issues -p <YourProjectKey>
```

{% endtab %}

{% tab title="WINDOWS (POWERSHELL)" %}
SonarQube Cloud, EU region:

```powershell
$env:SONARQUBE_CLI_TOKEN = "<YourUserToken>"
$env:SONARQUBE_CLI_ORG = "<YourOrganizationKey>"
sonar list issues -p <YourProjectKey>
```

SonarQube Server:

```powershell
$env:SONARQUBE_CLI_TOKEN = "<YourUserToken>"
$env:SONARQUBE_CLI_SERVER = "<YourSonarQubeServerURL>"
sonar list issues -p <YourProjectKey>
```

These variables exist only for the current PowerShell session. To persist them across sessions, use `setx` or set them via **System Properties** > **Environment Variables**.
{% endtab %}
{% endtabs %}

### Use the CLI in a CI/CD pipeline

Store your token as a CI secret (`SONARQUBE_TOKEN` in the examples below) and inject it as `SONARQUBE_CLI_TOKEN`.

{% tabs %}
{% tab title="GITHUB ACTIONS" %}

```yaml
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install SonarQube CLI
        run: curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh | bash
      - name: Scan for secrets
        env:
          SONARQUBE_CLI_TOKEN: ${{ secrets.SONARQUBE_TOKEN }}
          SONARQUBE_CLI_ORG: my-org
        run: |
          export PATH="$HOME/.local/share/sonarqube-cli/bin:$PATH"
          sonar analyze secrets .
```

{% endtab %}

{% tab title="GITLAB CI" %}

```yaml
sonar-secrets:
  image: ubuntu:latest
  variables:
    SONARQUBE_CLI_TOKEN: $SONARQUBE_TOKEN
    SONARQUBE_CLI_ORG: my-org
  before_script:
    - apt-get update && apt-get install -y curl
    - curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh | bash
    - export PATH="$HOME/.local/share/sonarqube-cli/bin:$PATH"
  script:
    - sonar analyze secrets .
```

{% endtab %}
{% endtabs %}

`sonar analyze secrets` exits with code `51` when a secret is found, which fails the job by default. See [Exit codes](/sonarqube-cli/using-sonarqube-cli/exit-codes.md) for the full list.

## Related pages <a href="#related-pages" id="related-pages"></a>

* [Commands reference](/sonarqube-cli/using-sonarqube-cli/commands.md)
* [Exit codes](/sonarqube-cli/using-sonarqube-cli/exit-codes.md)
* [Quickstart guide](/sonarqube-cli/quickstart-guide.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/using-sonarqube-cli/environment-variables.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.