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

# Windows Installer packages (MSI)

> Write a real .msi from the same bach.toml for Group Policy, Configuration Manager and Intune: files, shortcuts, registry values, components and upgrades.

Companies that deploy with Group Policy, Configuration Manager or Intune ask for an `.msi`. `bach build --msi` writes one from the same `bach.toml`, next to the setup file.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach build --msi
```

```console theme={"theme":{"light":"github-light","dark":"github-dark"}}
Wrote dist/Hello-Setup-1.4.0.exe (11.2 MB)
Wrote dist/Hello-Setup-1.4.0.msi (9.8 MB), the Windows Installer package
  not in the MSI: [[run]] steps
```

The package is a real MSI database with its files in an embedded cabinet, not a wrapper around the setup file. Windows Installer installs, repairs, upgrades and removes it itself.

| In the MSI | How |
| - | - |
| Files and folders | Every file is its own component, with an id that stays the same across versions. |
| Shortcuts | Start menu (in the folder `installer.start_menu_folder` names, removed again), desktop and `[[shortcuts]]`, each in its own component, with the app's icon. |
| Registry, variables and integration | `[[registry]]`, `[[env]]`, `[[protocols]]`, `[[file_types]]` (as "Open with") and `[[context_menu]]`, written and removed where the setup file writes them. `{app}` is the install folder, here with a trailing backslash. |
| Options and components | One feature each, named like the setup file's `--with` ids: components by their id, and `desktop_shortcut`, `start_menu`, `autostart` and `path`. Ticked ones install by default; others with `ADDLOCAL=id`. |
| Start with Windows, PATH | The `Run` entry, and the install folder appended to the user's `PATH` and taken off again on removal. |
| Run steps | `[[run]]` steps start the packaged program after the files are in place or before they go (removal never stops for a failed step). |
| Requirements | A `windows` requirement is a launch condition on the Windows build. |
| Settings > Apps | Name, publisher, version, website, icon and install location. |
| Upgrades | A higher version replaces older ones. An older package refuses to replace a newer one. |
| Scope | `installer.scope = "machine"`: per machine, in Program Files. The default `"user"`: per user, in `%LOCALAPPDATA%\Programs`, no administrator rights. |

Not carried (and reported as `not in the MSI`): `[[migrate]]`, `[updates]`, user data folders, component downloads, requirements other than a Windows build in a quiet install, a run step's other exit codes, and `elevated` run steps in a per-user package. The texts Windows Installer shows itself are English.

## The window

Open the `.msi` (double-click it, or remove it under Settings > Apps) and you get the same window as the setup file's, not Windows Installer's plain progress box: the same style and layout, the install folder, the options, the license, the requirements, "Repair" and the removal page, in the user's language. The package carries a small copy of the setup program for it (about 10 MB).

The window asks the questions and then calls Windows Installer with the answers, so the install is a real one: the same files, shortcuts, registry values, upgrade rules and Settings > Apps entry as the table above, with a progress bar that follows Windows Installer's own. Cancelling makes Windows Installer undo what it did. A machine-wide package asks Windows for administrator rights once.

A quiet install (`msiexec /i ... /qn`, `/qb`, Group Policy, Intune) never shows the window. It runs Windows Installer's own install with the defaults and `ADDLOCAL`, so the license page and the requirements other than a Windows build apply only when the window is shown. Windows Installer's log of a window's run is `%TEMP%\<app id>-msi.log`, next to the setup log.

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
msiexec /i Hello-Setup-1.4.0.msi /qn                 # install silently
msiexec /i Hello-Setup-1.4.0.msi /qn ADDLOCAL=ALL    # with every optional component
msiexec /x Hello-Setup-1.4.0.msi /qn                 # remove it
```

* The version has to be three numbers (`1.4.2`; 255, 255, 65535 at most), no suffix.
* Up to 2 GB and 32,000 files. Names are written in Windows-1252; other characters show as `?`.
* An app with `[access]` can't be an MSI. The package is x64 and isn't signed by `--sign`: sign it with `signtool`.


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