> 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/administration/system-status.md).

# Check system status

Check SonarQube CLI authentication, network settings, binaries, and integrations with \`sonar system status\`.

`sonar system status` gives you a single diagnostic view of your SonarQube CLI installation: whether your token is valid, which proxy, custom CA certificate, and client certificate settings the CLI resolved, which auxiliary binaries are installed, which integrations are configured, whether a configured MCP server has a ready container runtime, Vortex entitlement and usage when you're authenticated to an entitled connection, and whether a CLI update is available.

The command does not require authentication. It still reports whether saved credentials exist and, when possible, verifies the token against your SonarQube server.

## Run the status check

```bash
sonar system status
```

The output starts with a banner and a system check headline:

* **SYSTEM CHECK: Healthy** when authentication and integration configuration look good.
* **SYSTEM CHECK: Issues found** when the token is missing or invalid, when an MCP config file is present but malformed, when a configured MCP server has no ready container runtime, when `SONARQUBE_CLI_MCP_WSL` is invalid on Windows, when an Antigravity secrets hook is installed but its configuration or backing script is invalid, when client certificate configuration is invalid, or when Vortex is installed but your connection is no longer entitled to it.

Authentication is reported as one of:

* **Not Set**: no credentials from environment variables or a saved login
* **Active**: token validated successfully
* **Invalid**: token rejected by the server
* **Set Unverified**: a token is stored but the server could not be reached to validate it. When the failure is due to a network or TLS problem, the output includes the underlying error message (for example, a connection timeout or certificate error).

## What the report includes

| Section             | What it shows                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication**  | Active server URL, organization (SonarQube Cloud), and the current token state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **Binaries**        | Auxiliary tools the CLI downloaded (for example, the secrets engine and SCA scanner), their paths, versions, and whether a newer pinned version is available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Cache**           | Whether log, SCA scanner cache, and global Git hook directories exist under `~/.sonar/sonarqube-cli/`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Integrations**    | Each `sonar integrate` install with its config path. Most agents report **CONFIGURED**, and OpenAI Codex reports **INSTALLED** with the recorded installation path. For Codex, the row also lists managed Sonar hook events when a managed requirements file contains Sonar hook commands. See [Check Codex installation status](#check-codex-installation-status). For most agents, MCP Server status is shown (not configured, configured, or invalid config). For Antigravity, Secrets Hook status is also shown when a secrets hook is recorded in state. When at least one MCP server is configured, one shared MCP Runtime line reports Docker, Podman, or nerdctl. See [Check the MCP container runtime](#check-the-mcp-container-runtime).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Network**         | Resolved proxy, custom CA certificate, and client certificate settings, including the configuration source (`SONAR_*` environment variables, stored `network.*` `sonar config` keys, or generic `HTTPS_PROXY` / `NODE_EXTRA_CA_CERTS` variables). Proxy URLs redact embedded credentials. When a client certificate is configured, the section lists the certificate path and, for PEM files, the key path. For PKCS#12 bundles (`.p12` or `.pfx`), the key path is omitted and passphrase status is shown instead. When client certificate configuration is invalid, the section shows the error. When nothing is configured, the section reports that no advanced network configuration was detected. See [Advanced network configuration](https://docs.sonarsource.com/sonarqube-cli/administration/advanced-network-configuration.md) for details. The SonarQube MCP Server launched by the CLI uses these settings. A note warns that not all CLI features currently honor proxy and certificate settings (for example, secrets hooks, Vortex context, and Software Composition Analysis). See [environment-variables.md](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity). |
| **Vortex**          | When you're authenticated to a SonarQube Cloud or SonarQube Server 2026.5 or newer Enterprise or Data Center edition connection. Shows entitlement status and Vortex context usage against your plan limit. Omitted when Vortex does not apply to your connection. Status values: **Active**, **Active (quota exhausted)**, **Not entitled**, **Not available**, **Unknown (check failed)**, or **Configured organization is not accessible with this token**. Usage numbers appear on SonarQube (Server, Cloud) while you're entitled; they're omitted once your quota is exhausted. Entitlement loss marks the check unhealthy only when Vortex is installed through `sonar integrate`; quota exhaustion, check failures, and organization membership mismatches stay healthy. For a membership mismatch, run [`sonar auth status`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-auth-status) for next steps.                                                                                                                                                                                                                                                                                           |
| **Recommendations** | Suggested next steps such as `sonar auth login`, `sonar update` for an install-script copy, `brew upgrade --cask sonarqube-cli` for a Homebrew cask, or the original installation method for any other copy, fixing invalid client certificate configuration, re-running an integrate command to fix MCP or secrets hook configuration, installing or repairing Docker, Podman, or nerdctl when a configured MCP server has no ready runtime, or re-enabling Vortex, asking your administrator (SonarQube Server), or removing its integration when entitlement is lost.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

When saved credentials are present, at least one integration shows MCP Server status **configured**, and the saved SonarQube Server or SonarQube Community Build URL uses a loopback host, **Recommendations** includes guidance that starts with `MCP container networking:`. A non-loopback `mcp.container.serverUrl` suppresses that guidance. It does not by itself mark the check unhealthy. See [Reach a SonarQube Server on the same machine](https://docs.sonarsource.com/sonarqube-cli/administration/advanced-network-configuration.md#reach-a-sonarqube-server-on-the-same-machine).

## Check the MCP container runtime <a href="#check-the-mcp-container-runtime" id="check-the-mcp-container-runtime"></a>

When at least one integration shows MCP Server status **configured**, the report adds one shared line, `MCP Runtime`. An invalid or missing MCP configuration does not add that line by itself. The check asks Docker, then Podman, then nerdctl to run `info`. It does not download the MCP image, which means a ready runtime does not prove that the server will start.

* A runtime that is not installed is skipped.
* The first runtime whose `info` command succeeds is ready. The line is `MCP Runtime: READY (docker)`, or the same form for `podman` or `nerdctl`.
* If `info` does not answer within 3 seconds, the check stops on that runtime. The line is `MCP Runtime: NOT RESPONDING (docker)`. It does not try the next runtime, and on Windows it does not try WSL.
* If `info` fails and a later runtime answers, that later runtime is ready.
* If no `info` command succeeds, the first installed runtime is not ready. The line is `MCP Runtime: NOT READY (docker)`. A runtime that is on your PATH but fails both `info` and `--version` is still not ready when no later runtime answers.
* If every runtime is missing, the line is `MCP Runtime: NOT FOUND`.

On Windows, a runtime reached through WSL adds `via WSL`, for example `MCP Runtime: READY (docker via WSL)`. `SONARQUBE_CLI_MCP_WSL` selects native runtimes or WSL the same way as [`sonar run mcp`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md#mcp-container-runtime-on-windows). `auto` tries WSL only when Docker, Podman, and nerdctl are all missing. An installed native runtime that is not ready does not fall back to WSL.

Anything other than **READY** marks the check **Issues found** and adds one recommendation:

* Not ready: `SonarQube MCP Server cannot start because docker is not ready. Start or repair it.` The runtime name matches the line above, including `via WSL` when the check used WSL.
* Not responding: `docker is not responding to the runtime check. The MCP launcher may wait for it.`
* Not found: `SonarQube MCP Server needs Docker, Podman, or nerdctl. Install and start one to use the MCP server.`

On Windows, an invalid `SONARQUBE_CLI_MCP_WSL` value does not stop the command. There is no MCP Runtime line. **Recommendations** includes `SONARQUBE_CLI_MCP_WSL must be auto, always, or never.`, and the check is unhealthy. macOS and Linux ignore the variable.

After `sonar integrate` for an agent, the same check runs when that agent's recorded install includes the MCP server. A missing or not ready runtime prints the recommendation on stderr as a warning, and the install still completes. On Windows, an invalid `SONARQUBE_CLI_MCP_WSL` value prints that error as a warning instead. A ready runtime prints no warning.

In JSON, `mcpRuntime` is `null` when no configured MCP server was checked, or when `SONARQUBE_CLI_MCP_WSL` is invalid on Windows. Otherwise it is an object:

* Ready: `{ "status": "ready", "runtime": "docker", "viaWsl": false }`
* Not ready, including through WSL: `{ "status": "not_ready", "runtime": "podman", "viaWsl": true }`
* Not responding: `{ "status": "not_ready", "runtime": "docker", "viaWsl": false, "reason": "timeout" }`
* Not found: `{ "status": "not_found" }`

`runtime` is `docker`, `podman`, or `nerdctl`. `reason` is present only for a runtime that did not answer in time. `healthy` is `false` when the runtime is not ready, is not found, or the Windows variable is invalid.

## Check Codex installation status <a href="#check-codex-installation-status" id="check-codex-installation-status"></a>

Other integrations report **CONFIGURED**. OpenAI Codex reports **INSTALLED** and includes the recorded installation path when one is stored:

```
  • Codex: INSTALLED (~/.codex/hooks.json)
    Managed Sonar hooks (/etc/codex/requirements.toml): SessionStart, PostToolUse
```

The second line appears only when the managed requirements file contains Sonar hook commands. On macOS and Linux that file is `/etc/codex/requirements.toml`. On Windows it is `%ProgramData%\OpenAI\Codex\requirements.toml`. If `ProgramData` is unset, the path starts at `C:\ProgramData`.

The line lists only events whose commands are Sonar hooks. Commands for other tools in the same file are omitted. The CLI reads the file and does not run those commands. If the file is missing, empty, invalid, or has no Sonar hook commands, that is not an error: status prints only the **INSTALLED** line.

`--format json` lists Codex with the other integrations. It does not include the managed-hooks line.

For token verification details, see [`sonar auth status`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-auth-status). For what reset clears, see [Reset the CLI](https://docs.sonarsource.com/sonarqube-cli/administration/system-reset.md).

## Machine-readable output

For scripts and automation, pass `--format json`:

```bash
sonar system status --format json
```

`--json` has been deprecated since 1.9 and will be removed in a future version. It still prints the same JSON as `--format json`, and the CLI prints a deprecation warning on stderr. Use `--format json` instead. Passing `--json` selects JSON even when `--format` is also set.

The JSON document includes the CLI version, authentication summary, a `network` object (proxy URLs, `noProxy` list, CA certificate path, `clientCertificate` object with certificate path, optional key path for PEM files, `passphraseSet` for PKCS#12 bundles, or an `error` when configuration is invalid, and human-readable source labels), binaries, cache directories, integrations, MCP configuration flags, an `mcpRuntime` object when a configured MCP server was checked, Antigravity secrets hook flags (`configured` and `valid` under `hooks` when applicable), a `vortex` object, a top-level `healthy` boolean, and a `recommendations` array. `mcpRuntime` is `null` when no configured MCP server was checked, or when `SONARQUBE_CLI_MCP_WSL` is invalid on Windows. See [Check the MCP container runtime](#check-the-mcp-container-runtime). When MCP container networking guidance applies, that array includes a string that starts with `MCP container networking:`. Token state in JSON uses `not_set`, `active`, `invalid`, or `set_unverified`. When token verification fails because the server is unreachable, the authentication object may also include `tokenError` with the underlying network or TLS message.

The `vortex` object is `{ "applicable": false }` when Vortex status does not apply (for example, SonarQube Server before 2026.5 Enterprise, or SonarQube Cloud without a resolved organization). When applicable, it includes `applicable: true`, a `status` of `enabled`, `over_consumption`, `not_entitled`, `check_failed`, or `organization_not_accessible`, and a `consumption` object with `consumed` and `limit` only on SonarQube Cloud while you're actively entitled.

## When to use it

* After `sonar auth login` or when integrations stop working: confirm the token, network settings, MCP config, container runtime, Vortex entitlement, and (for Antigravity) secrets hook are healthy
* Before filing a support request: capture the status output
* In CI diagnostics when the CLI behaves unexpectedly but commands still run

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

* [Commands reference](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md)
* [Reset the CLI](https://docs.sonarsource.com/sonarqube-cli/administration/system-reset.md)
* [State and storage](https://docs.sonarsource.com/sonarqube-cli/administration/state-and-storage.md)
* [Advanced network configuration](https://docs.sonarsource.com/sonarqube-cli/administration/advanced-network-configuration.md)
* [Output formats](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/output-formats.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/administration/system-status.md?ask=<question>&goal=<user_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.
