> 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/using-sonarqube-cli/environment-variables.md). # Environment variables Use environment variables to configure the SonarQube CLI without running `sonar auth login`. This is 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 isn't 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 The CLI resolves credentials in this 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 don't interfere with each other. ## CLI home directory | Variable | Description | Default | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `SONAR_USER_HOME` | Root directory for Sonar product data on your machine. The CLI stores `state.json`, binaries for [Secrets detection](/sonarqube-cli/analysis/secrets-detection.md), [Sonar Vortex context augmentation](/agent-centric-development-cycle/guide/sonar-vortex-context-augmentation.md), and [Software Composition Analysis (SCA)](/sonarqube-cli/analysis/sca.md) add-ons, hooks, and logs under `/sonarqube-cli/`, and the anonymous telemetry user ID at `/user`. | `~/.sonar` | Use this variable to redirect CLI state, downloaded executables, and the telemetry user ID to a different location (for example, an isolated temp directory in automated tests). On Windows machines where only certain directories allow executable files, set `SONAR_USER_HOME` to an allowed path: the CLI downloads add-on binaries (such as `sonar-secrets`) to `/sonarqube-cli/bin/`. It doesn't move the installed `sonar` binary. ## Network connectivity Set these variables when the CLI runs behind a corporate proxy or must trust a custom CA certificate for HTTPS calls to SonarQube Server or Cloud (including binary downloads from `binaries.sonarsource.com`). | Variable | Description | Default | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `SONAR_HTTPS_PROXY_URL` | Proxy URL for HTTPS requests (for example, `https://proxy.corp.com:8080`). Include credentials in the URL when required (`https://user:pass@proxy:8080`). | - | | `SONAR_HTTP_PROXY_URL` | Proxy URL for HTTP requests. | - | | `SONAR_NO_PROXY` | Comma-separated list of hosts that bypass the proxy. Supports hostname suffix matching, `*.domain.com` wildcards, and port-specific entries such as `host:9000`. Set together with a `SONAR_*` proxy variable from the same tier. | - | | `SONAR_CA_CERT` | Path to a PEM file with one or more custom CA certificates to trust for TLS connections, in addition to the system root store. | - | | `SONAR_TLS_CLIENT_CERT` | Path to a client certificate for mutual TLS (mTLS) authentication: a PEM file, or a PKCS#12 bundle (`.p12` or `.pfx`) that contains the certificate and private key. Requires `SONAR_TLS_CLIENT_KEY_FILE` when the path is not a PKCS#12 bundle. | - | | `SONAR_TLS_CLIENT_KEY_FILE` | Path to the PEM private key that matches `SONAR_TLS_CLIENT_CERT`. Required when `SONAR_TLS_CLIENT_CERT` points to a PEM certificate file. | - | | `SONAR_TLS_CLIENT_PASSPHRASE` | Passphrase for an encrypted private key or a PKCS#12 bundle. | - | The CLI also reads `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` (or lowercase variants), and `NODE_EXTRA_CA_CERTS` as fallbacks however, `SONAR_*` variables take effect when both are set. Use the `SONAR_*` variables for explicit configuration, as support for the standard ones may change in future versions. Client certificate variables (`SONAR_TLS_CLIENT_*`) are read only from `SONAR_*` environment variables; there is no generic fallback. HTTPS targets use `SONAR_HTTPS_PROXY_URL`; HTTP targets use `SONAR_HTTP_PROXY_URL`. Set `SONAR_NO_PROXY` when specific hosts or domains should connect directly. Run `sonar system status` to confirm which proxy, custom CA certificate, and client certificate settings the CLI resolved and where they came from. See [Check system status](/sonarqube-cli/administration/system-status.md). When the CLI launches the SonarQube MCP server (`sonar run mcp` or agent integrations), it applies the same proxy and certificate settings. See [Advanced network configuration](/sonarqube-cli/administration/advanced-network-configuration.md). ### Route traffic through a corporate proxy {% tabs %} {% tab title="MACOS, LINUX (BASH/ZSH)" %} ```bash export SONAR_HTTPS_PROXY_URL=https://proxy.corp.com:8080 export SONAR_NO_PROXY=localhost,127.0.0.1,.corp.com export SONAR_CA_CERT=/etc/ssl/corp-ca.pem sonar list issues -p ``` {% endtab %} {% tab title="WINDOWS (POWERSHELL)" %} ```powershell $env:SONAR_HTTPS_PROXY_URL = "https://proxy.corp.com:8080" $env:SONAR_NO_PROXY = "localhost,127.0.0.1,.corp.com" $env:SONAR_CA_CERT = "C:\certs\corp-ca.pem" sonar list issues -p ``` {% endtab %} {% endtabs %} For proxy workarounds (NTLM, PAC files) and custom CA certificate setup, see [Advanced network configuration](/sonarqube-cli/administration/advanced-network-configuration.md). ## Examples ### Authenticate in a shell {% tabs %} {% tab title="MACOS, LINUX (BASH/ZSH)" %} SonarQube Cloud, EU region: ```bash export SONARQUBE_CLI_TOKEN= export SONARQUBE_CLI_ORG= sonar list issues -p ``` SonarQube Cloud, US region: ```bash export SONARQUBE_CLI_TOKEN= export SONARQUBE_CLI_ORG= export SONARQUBE_CLI_SERVER=https://sonarqube.us sonar list issues -p ``` SonarQube Server: ```bash export SONARQUBE_CLI_TOKEN= export SONARQUBE_CLI_SERVER= sonar list issues -p ``` {% endtab %} {% tab title="WINDOWS (POWERSHELL)" %} SonarQube Cloud, EU region: ```powershell $env:SONARQUBE_CLI_TOKEN = "" $env:SONARQUBE_CLI_ORG = "" sonar list issues -p ``` SonarQube Server: ```powershell $env:SONARQUBE_CLI_TOKEN = "" $env:SONARQUBE_CLI_SERVER = "" sonar list issues -p ``` 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 * [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) * [Advanced network configuration](/sonarqube-cli/administration/advanced-network-configuration.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/using-sonarqube-cli/environment-variables.md?ask=&goal= ``` `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.