> 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 Non-interactive SonarQube CLI configuration for CI/CD pipelines, container builds, and headless environments. 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 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`. > **Note:** `SONAR_TOKEN`, `SONAR_AUTH_TOKEN`, and properties like `SONARQUBE_SOURCE_DIR` and `headerFormat` belong to the SonarScanner CLI, not the SonarQube CLI. For the SonarQube CLI, use `SONARQUBE_CLI_TOKEN` and the other `SONARQUBE_CLI_*` variables described below. See the SonarScanner CLI docs for [SonarQube Server](https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/scanners/sonarscanner/) or [SonarQube Cloud](/sonarqube-cloud/analyzing-source-code/scanners/sonarscanner-cli.md). | 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`. `SONARQUBE_CLI_SERVER` must be an absolute `http` or `https` URL with a host when environment-variable authentication uses it. A path, a port, and a trailing slash are allowed. The CLI fails with exit code `2` when the value uses another scheme, includes a username or password, or contains a control character, such as a line break or a tab. When `SONARQUBE_CLI_ORG` is also set, the host must be `sonarcloud.io` or `sonarqube.us`. Any other host fails with exit code `2`. The error names `sonarcloud.io` and `sonarqube.us`. > **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. On SonarQube Cloud, a valid `SONARQUBE_CLI_TOKEN` can still lack membership in `SONARQUBE_CLI_ORG`. Run [`sonar auth status`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-auth-status) to check. The command fails with exit code `1` when the organization is not accessible. Regenerate the token from **My Account > Access Tokens**, or ask an organization administrator to add your account. ### 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. [`sonar context`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-context) uses environment credentials only when the server and organization match the connection recorded for the current project. Credentials for a different server or organization are ignored. The CLI then looks up a saved token for the recorded connection. 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. When environment variables supply your credentials, the CLI records connection metadata in `state.json` on the first authenticated command (the same fields `sonar auth login` writes), but it never stores the token in your system keychain. Commands such as `sonar auth status` and `sonar system status` read that metadata. Unset the variables to stop using them. [`sonar auth logout`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-auth-logout) does not unset the variables. If no keychain token exists, it reports that you're already logged out. If you previously ran `sonar auth login`, logout still removes that saved token even while the environment variables are in use. If you run [`sonar auth login`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-auth-login) while those variables are set, the CLI warns you and asks whether to continue (default No). Declining cancels the login before the CLI contacts the server. If you continue, the token is saved to the keychain but is not used until you unset the variables. `sonar auth login --with-token` does not prompt: it fails until you unset `SONARQUBE_CLI_TOKEN` and `SONARQUBE_CLI_SERVER` or `SONARQUBE_CLI_ORG`. > **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. > **Note:** Username and password authentication is not supported, including legacy Basic authentication used by older SonarQube Server versions. Authenticate with a user token. ## 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](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md), and [Software Composition Analysis (SCA)](/sonarqube-cli/analysis/sca.md) add-ons, hooks, logs, and a local stats database under `/sonarqube-cli/`, and the anonymous telemetry user ID at `/user`. | `~/.sonar` | Use this variable to redirect CLI state, downloaded executables, the local stats database, 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 does not move the installed `sonar` binary. When `SONAR_USER_HOME` is set at `sonar integrate` time, the CLI embeds the resolved path in the generated MCP server configuration so agent-launched MCP servers read state and credentials from the same location. Re-run `sonar integrate` to refresh an existing MCP entry after you change this variable. ## Experimental commands | Variable | Description | Default | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `SONARQUBE_CLI_ALPHA` | Set to `1` or `true` to expose Alpha commands in help and enable them at runtime. Alpha commands are experimental and omitted from published documentation. | - | ## Logging Set `LOG_LEVEL` to choose the level written to `sonarqube-cli.log` for the current process. The file is `~/.sonar/sonarqube-cli/logs/sonarqube-cli.log`, or `/sonarqube-cli/logs/sonarqube-cli.log` when [`SONAR_USER_HOME`](#cli-home-directory) is set. The CLI does not print these log lines in the terminal. | Variable | Description | Default | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | `LOG_LEVEL` | File log level. Use `DEBUG`, `INFO`, `WARN`, `ERROR`, or `SILENT`. A recognized value overrides a stored [`log.level`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-set). Any other value is ignored. | Stored `log.level`, or `INFO` | Store a level for later commands with [`sonar config set log.level`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-set). Remove it with [`sonar config unset log.level`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-unset). The CLI reads the stored level at startup. `LOG_LEVEL` overrides that stored value when it is a recognized level. If the CLI cannot read the stored value, or the stored value is not recognized, it ignores that value. When neither source supplies a recognized level, the level is `INFO`. ## 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, unbracketed IPv6 addresses such as `::1`, and port-specific entries such as `host:9000` or `[::1]:9000`. Taken from the same source as the proxy URL. | - | | `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. A PEM file also needs `SONAR_TLS_CLIENT_KEY_FILE` or `network.tls.clientKey`. | - | | `SONAR_TLS_CLIENT_KEY_FILE` | Path to the PEM private key that matches the client certificate. Required for a PEM certificate unless `network.tls.clientKey` is set. Not used for a PKCS#12 bundle. | - | | `SONAR_TLS_CLIENT_PASSPHRASE` | Passphrase for an encrypted PKCS#8 private key or a PKCS#12 bundle. | - | The CLI checks three sources in this order: the matching `SONAR_*` variable, then the matching stored `sonar config` key, then a generic variable for proxy and custom CA settings only (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` or their lowercase forms, and `NODE_EXTRA_CA_CERTS`). The custom CA certificate and each client certificate setting use the first source that has a value. Client certificate settings have no generic fallback, so a `SONAR_*` variable can override one stored key while the others stay stored. The HTTPS proxy URL, HTTP proxy URL, and no-proxy list are one group. The highest-priority source that sets either proxy URL supplies all three. A no-proxy value alone does not select that source. If the CLI cannot read a stored key, it treats that key as unset. Prefer the `SONAR_*` variables for explicit configuration, because support for the generic variables may change in a future version. The stored key names are in [Advanced network configuration](/sonarqube-cli/administration/advanced-network-configuration.md). Store the matching key with [`sonar config set`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-set). Remove it with [`sonar config unset`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-unset). For a sensitive key, omit the value and type it at the masked prompt. 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. Agent integrations also forward a custom [`SONAR_USER_HOME`](#cli-home-directory) into the MCP server declaration when you set it before running `sonar integrate`. 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,::1 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,::1" $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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.