> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bach builds Windows installers from one bach.toml with the bach command: bach init, bach check, bach preview, bach build. Installs are per user and need no administrator rights by default. installer.scope = "machine" installs for every user after one Windows prompt. On Windows, run setup files with Start-Process -Wait -PassThru in PowerShell, and give signtool arguments that start with the word sign.

# bach update: update bach to the newest release

> bach update installs the newest Bach release from GitHub, checks its SHA-256 first and keeps the old files if a step fails. Also covers the update notice.

`bach update` brings `bach` itself up to date. When a newer release exists on GitHub, `bach` also says so at the end of a command run in a terminal, so you know to run it.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach update               # install the newest release
bach update 0.7.1         # install exactly this version (an older one is fine)
bach update --check       # only say whether a newer release exists
bach update --force       # install again even if this version is already installed
```

```console theme={"theme":{"light":"github-light","dark":"github-dark"}}
$ bach update
Updating Bach 0.7.1 to 0.8.0
  Downloading bach-0.8.0-windows-x64.zip…
  Updated      C:\Users\you\AppData\Local\Programs\bach-cli\bach.exe
  Updated      C:\Users\you\AppData\Local\Programs\bach-cli\bach-setup.exe
Bach 0.8.0 is installed. What's new: https://github.com/usebach/bach/releases/tag/v0.8.0
```

| Argument or flag | Meaning |
| - | - |
| `VERSION` | Install exactly this version, like `0.8.0` (a leading `v` is dropped). Leave it out for the newest release. Pre-releases are never picked as "newest". |
| `--check` | Say whether a newer release exists, and change nothing. It can't be combined with `VERSION` or `--force`. |
| `--force` | Install even when that version is already the one you have, to repair a copy. |

## The update notice

When a newer release is out, the end of a command shows:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
A new version of Bach is available: 0.7.1 to 0.8.0.
Update with: bach update
```

The notice never makes a command wait. A background `bach update-refresh` asks GitHub (or, for a copy installed with npm, the npm registry, so the notice never announces a version npm doesn't have yet) every time you run a command (not again within 10 seconds; a check that fails, offline for example, is forgotten) and keeps the answer in a small file in Bach's cache folder (`update-check.json`, see [Files and locations](/docs/reference/setup/files-and-locations.md)). A command only reads that file, so the first run after a release says nothing and the next one does.

It is shown only when a person is looking, and never when:

* standard error is not a terminal (a pipe, a log file),
* you pass `--json`,
* the `CI` environment variable is set,
* `BACH_NO_UPDATE_CHECK` is set to any value (see [Environment variables](/docs/reference/setup/environment-variables.md)),
* this `bach` was built from a checkout of the source (`target\debug` or `target\release`).

`bach update` and `bach update --check` always look at GitHub themselves, and update the file the notice reads.

## How bach is replaced

**1. Find the release**

`bach` asks GitHub for the newest release, or the tag you named. It takes only the tag and the file names from the answer and builds the download address itself, under `https://github.com/usebach/bach/releases/download`.

**2. Download and check**

The archive for your system and its `.sha256` go to a staging folder next to `bach`. If the SHA-256 doesn't match, nothing is changed.

**3. Try the new program**

The archive is unpacked and the new `bach` must start and report the version that was asked for.

**4. Swap**

`bach` and the `bach-setup.exe` beside it are replaced. Each old file is kept until all new ones are in place, and put back if a step fails. Windows can't delete a running program, so `bach.exe.old` is removed the next time `bach` starts.

## Installed with a package manager

Only a copy made of loose files (the release download, `install.ps1` or `install.sh`) replaces itself. A copy that another tool manages is that tool's to update, so `bach update` stops and names the command instead. The notice shows the same command. For npm, `bach update --check` and the notice compare with the newest version on npm, not on GitHub.

If npm prints `npm warn install-scripts` lines during the update, they are about your other global packages. `@usebach/cli` has no install script.

| Installed with | Recognised by the path | Update with |
| - | - | - |
| npm | inside `node_modules` | `npm update --global @usebach/cli` |
| Scoop | inside `scoop\apps` | `scoop update bach` |
| winget | inside `Microsoft\WinGet` | `winget upgrade bach` |
| Cargo | `.cargo\bin` or `$CARGO_HOME\bin` | `cargo install --git https://github.com/usebach/bach bach-cli --locked --force` |
| A checkout of the source | `target\debug` or `target\release` | `git pull`, then `cargo build --release` |

A system-wide install in `%ProgramFiles%\bach-cli` needs administrator rights to be replaced. Run `bach update` from an administrator terminal, or run `install.ps1` again with `BACH_SCOPE` set to `system`.

## Machine-readable output

With `--json`, standard output is one JSON object. It holds `current` (this bach), `latest` (the release looked at), `update_available`, `install` (`standalone`, `npm`, `scoop`, `winget`, `cargo` or `checkout`) and, unless `--check` was given, `updated`.

```console theme={"theme":{"light":"github-light","dark":"github-dark"}}
$ bach update --check --json
{"current":"0.7.1","install":"standalone","latest":"0.8.0","ok":true,"update_available":true,"warnings":[]}
```

## Errors

| Message | What to do |
| - | - |
| `Couldn't reach GitHub …` | Check your connection and try again. `bach` needs `curl` (Windows 10 and later have it) or PowerShell. |
| `The download doesn't match its published SHA-256, so nothing was changed.` | Try again. If it keeps failing, download the zip from the [releases page](https://github.com/usebach/bach/releases). |
| `This bach is managed by …` | Run the command the message names. |
| `Couldn't write to …` | The folder needs administrator rights. See above. |
| `Bach X has no download for this system …` | That release has no file for your system. Use `cargo install`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.