> 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/state-and-storage.md). # State and storage Where the SonarQube CLI stores its state, credentials, binaries, and logs, plus how to audit them on a developer machine. Use this page to audit exactly what the SonarQube CLI writes to disk, where it lives, and how credentials are stored. ## On-disk layout CLI-specific data lives under `~/.sonar/sonarqube-cli/`. The stable anonymous telemetry user ID is stored one level up, at `~/.sonar/user`, so it can be shared across Sonar products on the same machine. Override the shared root with [`SONAR_USER_HOME`](/sonarqube-cli/using-sonarqube-cli/environment-variables.md#cli-home-directory). | Path | Contents | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `~/.sonar/user` | Stable anonymous telemetry user ID (shared across Sonar products). Contains a UUID only. | | `~/.sonar/sonarqube-cli/state.json` | CLI state (active connection ID, telemetry installation ID, installed integrations, installed binary metadata). | | `~/.sonar/sonarqube-cli/cli-config.properties` | Non-sensitive `sonar config` values, such as `log.level`, `telemetry.enabled`, and `stats.enabled`. [`sonar config set`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-set) writes them, [`sonar config get`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-get) prints one key, [`sonar config list`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-list) prints every key, and [`sonar config unset`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-unset) removes one key. A stored `log.level` sets the file log level at startup. `telemetry.enabled` and `stats.enabled` control those collections, and each stays enabled when its key is not set. `sonar system reset --all` removes this file. | | `~/.sonar/sonarqube-cli/telemetry/telemetry-events.ndjson` | Buffered telemetry events waiting to be flushed to SonarSource. | | `~/.sonar/sonarqube-cli/db/stats/` | Local stats database (`stats.db`). Stays on your machine and is never transmitted. Removed by `sonar system reset`. | | `~/.sonar/sonarqube-cli/bin/` | Auxiliary binaries downloaded on demand (the secrets detection engine and SCA scanner). | | `~/.sonar/sonarqube-cli/hooks/` | Git hook scripts installed by `sonar integrate git`. | | `~/.sonar/sonarqube-cli/logs/` | File log `sonarqube-cli.log`. See [Logging](/sonarqube-cli/using-sonarqube-cli/environment-variables.md#logging). | | `~/.sonar/sonarqube-cli/cli-tmp/` | Temporary files generated by the CLI (for example, PKCS#12 keystores converted for the MCP server). Removed when the MCP process exits or when you run `sonar system reset`. | If you upgraded from an earlier CLI version that stored the user ID at `~/.sonar/sonarqube-cli/user`, the CLI migrates it to `~/.sonar/user` on first use and removes the legacy file. 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, throttled update-check metadata (`config.updateCheck`), Beta command warning state (`config.betaCommandWarnings`), and other configuration hints. | | `telemetry` | Installation ID. Pending events are stored in `telemetry/telemetry-events.ndjson`, not in this file. Turn collection on or off with `telemetry.enabled` in `cli-config.properties`. | | `stats` | Removed after an update. The collection preference is `stats.enabled` in `cli-config.properties`. When that key is not set, collection stays enabled. Never transmitted. | | `dependencies` | Versions and paths of installed auxiliary binaries (secrets engine, SCA scanner, and Sonar Vortex context engine). | | `tools` | Legacy registry superseded by `dependencies`. Entries are folded into `dependencies.installed` on load. | | `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. | `cat` or `jq` this file at any time; it contains no secrets. When automatic update notices are enabled, `config.updateCheck` stores the ISO timestamp of the last remote version check (`lastCheckedAt`) and the latest stable version returned (`latestVersion`). The CLI reuses this cache for up to 24 hours, which means routine commands do not trigger repeated network requests. ## Where tokens are stored The CLI stores tokens 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:** `` for SonarQube Server, or `:` for SonarQube Cloud (one entry per connection). * **Sensitive config values** use the same service name and an account of `config/` (for example, `config/network.proxy.https`). [`sonar config set`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-set) stores them, [`sonar config get`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-get) and [`sonar config list`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-list) print `***` when a value is stored for those keys, and [`sonar config unset`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-unset) removes one key. To audit which tokens the CLI has saved, open your OS keychain and search for `sonarqube-cli`. To remove an active keychain-based connection, run [`sonar auth logout`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-auth-logout). Repeat after switching connections if you have saved multiple entries. When you authenticate with [environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md), the token stays in your environment and the CLI records connection metadata in `state.json` without writing a keychain entry. [`sonar auth logout`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-auth-logout) does not unset those variables. If no keychain token exists, it reports that you are already logged out. If a previous `sonar auth login` left a keychain token, logout removes that token when the keychain is available. If the keychain cannot be read or updated, logout still removes the saved connection and prints a warning. Delete the remaining keychain entry yourself. > **Warning:** **WSL has no keychain.** Under Windows Subsystem for Linux, no Secret Service is available by default. The interactive `sonar auth login` flow does not work as a result. 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 and integration installs. * [`sonar config set`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-set) writes non-sensitive values, including `telemetry.enabled` and `stats.enabled`, to `cli-config.properties` and sensitive values to the OS keychain. [`sonar config unset`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-unset) removes one key from the same place. * `telemetry/telemetry-events.ndjson` receives buffered telemetry events until they're flushed. * Analyzer runs write a local stats database under `db/stats/` when collection is enabled (the default). The database stays on your machine and is never transmitted. * The CLI appends file log output to `~/.sonar/sonarqube-cli/logs/sonarqube-cli.log`. The level is `LOG_LEVEL`, then a stored `log.level`, then `INFO`. * The CLI writes the auxiliary scanner binaries in `~/.sonar/sonarqube-cli/bin/` when first needed and reuses them afterwards. They're versioned and refreshed when you run `sonar update` on a standalone build. * Integration commands (`sonar integrate antigravity` / `claude` / `codex` / `copilot` / `cursor` / `opencode` / `git`) also write outside `~/.sonar/`: * AI agent integrations write to `~/.gemini/`, `~/.claude/`, `~/.codex/`, `~/.copilot/`, `~/.cursor/`, or `~/.config/opencode/`. * The Git integration writes to `~/.sonar/sonarqube-cli/hooks/` and sets `git config --global core.hooksPath`. `sonar integrate git --local` writes into the current repository (`.git/hooks/`, `.husky/`, or `.pre-commit-config.yaml`) instead. If an earlier CLI version installed per-repo hooks, leftover files may remain in those same locations. They are not migrated when you upgrade; see [Migrate project-scoped agent integrations](/sonarqube-cli/administration/self-update.md#migrate-project-scoped-agent-integrations). * [`sonar link`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-link) writes `.sonar-config.json` at the git repository root (or the current directory if you are not in a git repository). This file is not stored under `~/.sonar/`. Commit it so teammates share the same project binding. ## Repository project binding `.sonar-config.json` names one SonarQube project for the repository. The CLI reads it first during [project key auto-detection](/sonarqube-cli/integrations/integrations.md#project-key-auto-detection). Run [`sonar link`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-link) to create or overwrite it. On SonarQube Cloud EU (`https://sonarcloud.io`) and US (`https://sonarqube.us`), the `project` entry stores `projectKey`, a relative `path`, `region` (`eu` or `us`), and `organization`. On a SonarQube Cloud host with a non-default port, it stores `projectKey`, `path`, `serverUrl`, and `organization` instead of `region`. On SonarQube Server, it stores `projectKey`, `path`, and `serverUrl`. ## Auditing a developer machine To inspect what the CLI has set up: ```bash # What's been installed and where: jq '.integrations.installed' ~/.sonar/sonarqube-cli/state.json # Installed auxiliary binaries: jq '.dependencies.installed' ~/.sonar/sonarqube-cli/state.json # Active SonarQube connection: sonar auth status ``` For a clean removal, see [Uninstalling](/sonarqube-cli/administration/uninstall.md). ## Related pages * [Updating the CLI](/sonarqube-cli/administration/self-update.md) * [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) * [Commands reference](/sonarqube-cli/using-sonarqube-cli/commands.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/state-and-storage.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.