> 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 sonarqube-cli
```

The next CLI command after the upgrade migrates leftover project-scoped agent integrations to global scope. If that cannot finish, run `sonar auth login`, then `sonar update`. See [Migrate project-scoped agent integrations](#migrate-project-scoped-agent-integrations).

## Standalone build (install script or release binary)

`sonar update` upgrades the CLI in place. Under the hood it re-runs the same install script that put `sonar` on your system, replacing the binary. Your credentials and CLI state stay. 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)).

`sonar self-update` still works as a hidden compatibility alias. 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 does not migrate integrations.

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.

Follow the suggestion and run `sonar update`.

### Update to the latest version

```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.* 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`, even if the CLI is already up to date

`sonar update status` only reports versions. It does not migrate integrations. The deprecated `sonar update --status` flag behaves the same way.

You must be logged in. If you are not, the CLI prints a warning and leaves the project-scoped installs in place:

```
Could not migrate your agent integrations to global scope: you are not logged in. Run 'sonar auth login', then 'sonar update', to retry.
```

If some integrations cannot migrate, the CLI still completes the rest and prints:

```
Some integrations were left at project scope. Run 'sonar update' to retry.
```

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 <a href="#related-pages" id="related-pages"></a>

* [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=<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.