> 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/self-update.md). # Updating the CLI Keep the SonarQube CLI up to date. Update the SonarQube CLI to the latest version, or roll it back if an update breaks something. ## Homebrew ```bash brew upgrade --cask sonarqube-cli ``` The next CLI command after the upgrade migrates leftover project-scoped agent integrations to global scope. You must be logged in. If you are not, run `sonar auth login`. The migration retries the next time you upgrade with Homebrew. See [Migrate project-scoped agent integrations](#migrate-project-scoped-agent-integrations). The next command also moves a SonarQube Cloud token from an older `:` keychain account to the hostname account. See [Where tokens are stored](/sonarqube-cli/administration/state-and-storage.md#where-tokens-are-stored). `sonar update` does not update a Homebrew cask. The command exits with code 1 before it checks for a newer version, including when you pass `--force`, and prints: ``` CLI was installed via Homebrew and cannot be updated by `sonar update`. → Run `brew upgrade --cask sonarqube-cli` to update it. `sonar update` doesn't run Homebrew automatically so you stay in full control of your system updates. ``` The CLI does not run that upgrade for you. `sonar self-update` prints the same message. ## Standalone build (install script) `sonar update` updates only the binary installed by the install script: * macOS and Linux: `~/.local/share/sonarqube-cli/bin/sonar` * Windows: `%LOCALAPPDATA%\sonarqube-cli\bin\sonar.exe` It re-runs that install script and replaces the binary. Your credentials and CLI state stay. The next command moves a SonarQube Cloud token from an older `:` keychain account to the hostname account (see [Where tokens are stored](/sonarqube-cli/administration/state-and-storage.md#where-tokens-are-stored)). If an earlier version installed agent integrations into a repository, the upgrade migrates those to global scope (see [Migrate project-scoped agent integrations](#migrate-project-scoped-agent-integrations)). Mise, an MDM deployment, or a binary anywhere else cannot use `sonar update`. The command exits with code 1 before it checks for a newer version, including when you pass `--force`, and prints: ``` This CLI installation cannot be updated by sonar update. → Update it through your organization, package manager, or the method used to install it. ``` `sonar self-update` is a hidden compatibility alias for that same check and update. It has been deprecated since 1.4 and will be removed in a future version. Use `sonar update` instead. Each time you run it, the CLI prints a deprecation warning. ### Check whether an update is available ```bash sonar update status ``` The command prints the current version and the latest version, then exits without installing anything. It works from any installation and does not migrate integrations. When a newer version exists, an install-script copy is told to run `sonar update`. A Homebrew cask is told to run `brew upgrade --cask sonarqube-cli`. Any other install is told to update through your organization, package manager, or the method used to install it. Text output is the default. For a script, pass `--format json`. The payload is one object with `currentVersion`, `latestVersion`, and `upToDate`: ```bash sonar update status --format json ``` `sonar update --status` still checks without installing. It has been deprecated since 1.9 and will be removed in a future version. Use `sonar update status` instead. The flag prints a deprecation warning and does not accept `--format`. ### Automatic update notices After certain interactive commands complete successfully, the CLI may print a short notice on stderr when a newer stable version is available: ``` ℹ A new version of SonarQube CLI is available: 1.3.0 → 1.4.0 → Run `sonar update` to update to v1.4.0 ``` The notice never appears on stdout and does not mix with machine-readable command output. The CLI checks [binaries.sonarsource.com](https://binaries.sonarsource.com/) for the latest stable version at most once per day. Results are cached in `state.json` under `config.updateCheck` (see [State and storage](/sonarqube-cli/administration/state-and-storage.md)). The notice is shown only when: * The command exits with code `0` * You run in an interactive terminal (stdin, stdout, and stderr are TTYs) * `CI` is not set to `true` * The command does not use machine-readable output (`--format json`, `--format toon`, the deprecated `--json` flag, or other formatted output modes) Eligible commands include `sonar auth`, `sonar analyze`, interactive `sonar integrate`, `sonar list issues` with `--format table`, `sonar list projects` with `--format table`, `sonar list orgs` (the default format is `table`), and `sonar system status` in text output. `sonar list projects` defaults to JSON: pass `--format table` to see the notice. `sonar list orgs --format json`, `sonar system status --format json`, and the deprecated `--json` flag omit the notice. Other commands (including `sonar api`, `sonar context`, hidden hook handlers, and `sonar system reset`) never show the notice. On the install-script copy, the second line tells you to run `sonar update`. On a Homebrew cask, it tells you to run `brew upgrade --cask sonarqube-cli`: ``` → Run `brew upgrade --cask sonarqube-cli` to update it. ``` On any other install, it tells you to update through your organization, package manager, or the method used to install the CLI: ``` → Update it through your organization, package manager, or the method used to install it. ``` Follow the line that matches your install. `sonar update` does not add a second copy. ### Update to the latest version On an install-script copy, run: ```bash sonar update ``` If the latest version is the same as what you have, the command does not re-download the binary. It still retries the agent-integration migration if any project-scoped installs remain. To re-install the latest version regardless, use `--force`: ```bash sonar update --force ``` ### Rollback The update command does not maintain a previous-version snapshot. To go back to an earlier release, download a specific release binary from the [Sonar binaries repository](https://binaries.sonarsource.com/) and replace the binary at the install path manually. ### Platform notes * macOS / Linux: the update runs synchronously, streams progress to your terminal, and exits with the install script's status. * Windows: the update is spawned in a detached process so the running `sonar.exe` can be replaced. Your shell returns immediately; the new version is in place within a few seconds. ### Rolling out updates across a fleet For a managed rollout, *do not ask every developer to run `sonar update` interactively.* On a managed copy, that command exits with an error instead of installing a per-user binary next to the managed one. See [MDM deployment](/sonarqube-cli/administration/mdm-deployment.md). The bundled install scripts do not accept a version argument because it's not possible to pin a specific release. Instead: 1. Write your own install script that downloads a pinned version directly from the [Sonar binaries repository](https://binaries.sonarsource.com/) and places the binary at the install path. 2. Distribute that script through your usual managed-tooling channel. 3. Bump the pinned version in the script to promote a new release across the fleet. ## Migrate project-scoped agent integrations Earlier CLI versions could integrate with Claude Code, GitHub Copilot CLI, OpenAI Codex, Cursor, and Google Antigravity at the project level. Global scope is now the default for every agent integration. After you upgrade, the CLI moves existing project-scoped integrations to global scope in your user home and removes the project files from each repository they were installed in. The migration runs: * The first time you run a CLI command after the upgrade * When you run `sonar update`, before the command checks whether this copy can update itself On the install-script copy, that retry runs even when the CLI is already up to date. On any other install, the migration still retries, and `sonar update` then exits with code 1 without installing a second copy. Upgrade that CLI the way you installed it. `sonar update status` only reports versions. It does not migrate integrations. The deprecated `sonar update --status` flag behaves the same way. Both work from any installation. You must be logged in. If you are not, the CLI prints a warning and leaves the project-scoped installs in place. On the install-script copy: ``` Could not migrate your agent integrations to global scope: you are not logged in. Run 'sonar auth login'. Run 'sonar update' to retry. ``` On any other install: ``` Could not migrate your agent integrations to global scope: you are not logged in. Run 'sonar auth login'. The migration will retry when this CLI is upgraded to a newer version. ``` If some integrations cannot migrate, the CLI still completes the rest. On the install-script copy, it prints: ``` Some integrations were left at project scope. Run 'sonar update' to retry. ``` On any other install, it prints: ``` Some integrations were left at project scope. The migration will retry when this CLI is upgraded to a newer version. ``` Git hooks installed in a repository (`sonar integrate git --local`, or a per-repo Git install from an earlier CLI version) stay in that repository. They are not migrated. See [Install for this repository only](/sonarqube-cli/integrations/git-hooks.md#install-for-this-repository-only). If Claude Code is installed, the CLI skips the global migration for Cursor and Copilot, because installing their hooks globally would conflict with Claude Code's. It still removes Cursor's and Copilot's leftover project-scoped files. ## Related pages * [State and storage](/sonarqube-cli/administration/state-and-storage.md) * [Reset the CLI](/sonarqube-cli/administration/system-reset.md) * [Uninstalling](/sonarqube-cli/administration/uninstall.md) * [Overview](/sonarqube-cli/integrations/integrations.md) * [Release notes](https://github.com/SonarSource/sonarqube-cli/releases) --- # 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/self-update.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.