# State and storage

> **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 this page to audit exactly what the SonarQube CLI writes to disk, where it lives, and how credentials are stored.

## On-disk layout

All CLI state lives under a single directory in your home:

| Path                                | Contents                                                                                        |
| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| `~/.sonar/sonarqube-cli/state.json` | CLI state (active connection ID, telemetry preferences, installed integrations, tool metadata). |
| `~/.sonar/sonarqube-cli/bin/`       | Auxiliary binaries downloaded on demand (the secrets-scanning engine and SCA scanner).          |
| `~/.sonar/sonarqube-cli/hooks/`     | Git hook scripts installed by `sonar integrate git --global`.                                   |
| `~/.sonar/sonarqube-cli/logs/`      | CLI log files.                                                                                  |

The `sonar` binary itself is installed separately by the install script:

| Operating system | `sonar` binary location                      |
| ---------------- | -------------------------------------------- |
| macOS / Linux    | `~/.local/share/sonarqube-cli/bin/sonar`     |
| Windows          | `%LOCALAPPDATA%\sonarqube-cli\bin\sonar.exe` |

## What `state.json` contains

The state file contains these top-level keys:

| Key               | Purpose                                                                                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`         | The state schema version.                                                                                                                                         |
| `lastUpdated`     | ISO timestamp of the last state mutation.                                                                                                                         |
| `auth`            | Connection metadata (server URL, organization, active connection ID, token name). **Token values themselves are not stored here** — they live in the OS keychain. |
| `config`          | CLI version and configuration hints.                                                                                                                              |
| `telemetry`       | Telemetry enabled flag, installation ID, and any pending telemetry events not yet flushed.                                                                        |
| `tools`           | Versions and paths of installed auxiliary binaries (secrets engine, SCA scanner).                                                                                 |
| `integrations`    | Registry of installed agent/Git integrations and where each feature was installed.                                                                                |
| `agents`          | Legacy registry kept for backward compatibility with earlier CLI versions.                                                                                        |
| `agentExtensions` | Legacy registry kept for backward compatibility with earlier CLI versions.                                                                                        |

You can `cat` or `jq` this file at any time — it contains no secrets.

## Where tokens are stored

Tokens are stored in your operating system's secure credential store, not in plain files:

| OS      | Store                                    |
| ------- | ---------------------------------------- |
| macOS   | Keychain Access                          |
| Windows | Windows Credential Manager               |
| Linux   | Secret Service (GNOME Keyring / KWallet) |

* **Service name:** `sonarqube-cli`
* **Account name:** `<hostname>` for SonarQube Server, or `<hostname>:<organization-key>` for SonarQube Cloud (one entry per connection).

To audit which tokens the CLI has saved, open your OS keychain and search for `sonarqube-cli`. To clear them all, run [`sonar auth purge`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-auth-purge).

> **Warning:** **WSL has no keychain.** Under Windows Subsystem for Linux, no Secret Service is available by default, so the interactive `sonar auth login` flow won't work. Use [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md) for authentication in WSL.

## What the CLI writes when you run a command

* `state.json` is updated on most commands — connection changes, integration installs, telemetry buffering.
* `~/.sonar/sonarqube-cli/logs/` may receive log output for debugging.
* The auxiliary scanner binaries in `~/.sonar/sonarqube-cli/bin/` are written when first needed and re-used afterwards. They're versioned and refreshed on `sonar self-update`.
* Integration commands (`sonar integrate claude` / `copilot` / `git`) also write outside `~/.sonar/`:
  * AI agent integrations write to `~/.claude/` or `~/.copilot/` (global) or to your project directory (per-repo).
  * The Git integration writes to your repo's `.git/hooks/`, `.husky/`, or `.pre-commit-config.yaml`, or to `~/.sonar/sonarqube-cli/hooks/` for `--global`.

## Auditing a developer machine

To inspect what the CLI has set up:

```bash
# What's been installed and where:
cat ~/.sonar/sonarqube-cli/state.json | jq '.integrations.installed'

# Active SonarQube connection:
sonar auth status
```

For a clean removal, see [Uninstalling](/sonarqube-cli/administration/uninstall.md).

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

* [Telemetry and privacy](/sonarqube-cli/administration/telemetry-and-privacy.md)
* [Uninstalling](/sonarqube-cli/administration/uninstall.md)
* [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.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/administration/state-and-storage.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.