Developer

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

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 or SonarQube Cloud.

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:

Environment variables, if a valid combination is set, win over everything else.
Saved connection from sonar auth login (token from the system keychain) is used otherwise.
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.

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; sonar auth logout does not apply; unset the variables instead.

If you run 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.

Note: These variable names (SONARQUBE_CLI_*) are specific to the SonarQube CLI. The SonarQube MCP Server uses a different set (SONARQUBE_TOKEN, SONARQUBE_URL, SONARQUBE_ORG). They don't 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, Sonar Vortex context, and Software Composition Analysis (SCA) add-ons, hooks, and logs under <SONAR_USER_HOME>/sonarqube-cli/, and the anonymous telemetry user ID at <SONAR_USER_HOME>/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 <SONAR_USER_HOME>/sonarqube-cli/bin/. It doesn't 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.

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, with 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.

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 into the MCP server declaration when you set it before running sonar integrate. See Advanced network configuration.

Route traffic through a corporate proxy

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

$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 <YourProjectKey>

For proxy workarounds (NTLM, PAC files) and custom CA certificate setup, see Advanced network configuration.

Examples

Authenticate in a shell

SonarQube Cloud, EU region:

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

SonarQube Cloud, US region:

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

SonarQube Server:

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

SonarQube Cloud, EU region:

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

SonarQube Server:

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

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.

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 .

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 .

sonar analyze secrets exits with code 51 when a secret is found, which fails the job by default. See Exit codes for the full list.

PreviousCommands reference

NextOutput formats

Last updated 49 minutes ago

Was this helpful?

Authentication

Precedence

CLI home directory

Experimental commands

Network connectivity

Route traffic through a corporate proxy

Examples

Authenticate in a shell

Use the CLI in a CI/CD pipeline

Related pages