> ## 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.

# Install the bach command on Windows, macOS and Linux

> Install bach and its setup runtime with PowerShell, a shell script, Scoop, a release zip, cargo or the GitHub Action, and check the result with bach doctor.

Bach is two files that live side by side: `bach.exe`, the command you run, and `bach-setup.exe`, the installer window every setup file is built from. Pick the install method that fits your machine. None of them needs Rust, and none asks for administrator rights unless you ask for a system-wide install.

> [tab] npm
>
> With Node.js 18 or newer, on Windows, macOS and Linux:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> npm install --global @usebach/cli
> ```
>
> The package holds no program of its own. npm installs the matching `@usebach/cli-<platform>` package next to it, and `bach` starts that. No install script runs and nothing is downloaded afterwards, so it works with `--ignore-scripts`. On Windows the platform package also carries `bach-setup.exe`.
>
> * **In one project:** `npm install --save-dev @usebach/cli`, then `npx bach build`.
>
> * **Update:** `npm update --global @usebach/cli`.
>
> * **Remove:** `npm uninstall --global @usebach/cli`.
>
> > [!NOTE]
> >
> > Do not use `sudo` or an elevated shell. If npm's global folder is not writable, point npm at your own with `npm config set prefix ~/.npm-global`. If `bach` reports that its platform package isn't installed, npm ran with `--omit=optional`: install again without that flag.

> [tab] Windows (PowerShell)
>
> ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
> irm https://raw.githubusercontent.com/usebach/bach/main/install.ps1 | iex
> ```
>
> The script downloads the latest release (Windows on ARM gets its own build when the release has one), checks its SHA-256, and unpacks `bach.exe` and `bach-setup.exe` into `%LOCALAPPDATA%\Programs\bach-cli`. It then adds that folder to your user `PATH`. Open a new terminal to use it. Run the script again to update.
>
> > [!NOTE]
> >
> > The script never writes into a folder it did not create. If the target folder holds anything other than Bach's own two files, it stops and tells you. Set `BACH_INSTALL_DIR` to another, empty folder in that case.
>
> To install for every user of the PC, set the environment variable `BACH_SCOPE` to `system` before the line. Bach then goes to `%ProgramFiles%\bach-cli` and the machine's `PATH`. Windows asks for permission once (UAC), and only that script runs with it. If you decline, Bach is installed for you alone.

> [tab] macOS and Linux
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl -fsSL https://raw.githubusercontent.com/usebach/bach/main/install.sh | sh
> ```
>
> This installs `bach` to `~/.local/bin` (or `$BACH_INSTALL_DIR`) after checking the download's SHA-256. The Windows runtime it builds on, `bach-setup.exe`, is downloaded and checked automatically the first time you run `bach build`. Use this on CI runners that build Windows installers.
>
> To install for every user, pass `--system` to the script (`sh -s -- --system`). That installs to `/usr/local/bin` and uses `sudo` for that copy only, and only if the folder isn't writable by you. If `sudo` is missing or refused, `bach` is installed in `~/.local/bin` instead.

> [tab] Scoop
>
> ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
> scoop install https://raw.githubusercontent.com/usebach/bach/main/scoop/bach.json
> ```

> [tab] Zip download
>
> Download `bach-<version>-windows-x64.zip` from the [releases page](https://github.com/usebach/bach/releases), unzip it somewhere permanent and keep `bach.exe` and `bach-setup.exe` together. Use this when you cannot reach GitHub's raw files.

> [tab] cargo
>
> If Rust is already installed:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> cargo install --git https://github.com/usebach/bach bach-cli
> ```
>
> Then `bach` downloads its runtime when it needs it.

> [tab] GitHub Action
>
> ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
> - uses: usebach/bach@main
>   id: bach
>   with:
>     config: bach.toml
> - uses: actions/upload-artifact@v4
>   with:
>     path: ${{ steps.bach.outputs.setup }}
> ```
>
> See [Automate in CI](/docs/guides/ci.md) for all inputs and outputs.

## Keep bach up to date

When a newer release exists, `bach` says so at the end of a command run in a terminal. Run `bach update` to install it. That works for the PowerShell and shell scripts and for the zip download; a `bach` installed with npm, Scoop, winget or cargo is updated with that tool, and `bach update` names the command. See [`bach update`](/docs/reference/cli/update).

## Check the install

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach --version
bach doctor
```

`bach doctor` says whether the runtime, the config and the optional tools are in place, and exactly what to fix if not. See [`bach doctor`](/docs/reference/cli/doctor).

## Where Bach finds its runtime

Every installer is built on `bach-setup.exe`. When you run `bach build` or `bach preview`, `bach` looks for it in this order:

1. The path given with `--runtime`, or in the `BACH_RUNTIME` environment variable.
2. The file next to `bach` itself.
3. In a checkout of the Bach repository, the copy a `cargo build` left in `target\release` or `target\debug`.
4. A copy downloaded earlier. The cache is `%LOCALAPPDATA%\bach\runtime\<version>` on Windows, and `$XDG_CACHE_HOME/bach/runtime/<version>` (or `~/.cache/...`) elsewhere.
5. The one published with this version of Bach on GitHub, downloaded once and checked against its SHA-256 before use.

Set `BACH_NO_DOWNLOAD` to forbid the last step. All environment variables are listed in [Environment variables](/docs/reference/setup/environment-variables.md).

## Build from source

With Rust (stable) and the Visual Studio C++ build tools:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone https://github.com/usebach/bach.git
cd bach
cargo build --release
```

That gives `target\release\bach.exe` and `target\release\bach-setup.exe`.

## Next step

> [card] [Quickstart](/docs/quickstart.md)
>
> Write your first bach.toml and build a Setup.exe.


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