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

# Sign a setup file to reduce SmartScreen warnings

> Sign your finished Bach setup file with signtool so SmartScreen trusts it over time. Sign after bach build, verify it, then rewrite the update feed.

Windows SmartScreen warns about unsigned programs from publishers it does not know yet. A code-signing certificate makes the warning go away over time and shows your name as the publisher when people download and run your setup file. Bach setup files sign like any other program.

## Get signtool

`signtool` is part of the Windows SDK. Install the SDK and tick "Windows SDK Signing Tools for Desktop Apps". It is usually **not on your `PATH`**: typing `signtool` in PowerShell answers that the name is not recognised. Either open "Developer PowerShell for VS" from the Start menu, which knows it, or call it by its full path. The folder carries the SDK's version number, so list yours first:

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
Get-ChildItem "C:\Program Files (x86)\Windows Kits\10\bin" -Directory
& "C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64\signtool.exe" /?
```

Signing also needs a code-signing certificate that signtool can find, in your certificate store or on a hardware token. `/a` below picks the best one. Without a certificate signtool says that no certificates were found. When Bach signs for you (see below), it finds `signtool` in the SDK folder by itself.

## Sign after you build

**1. Build**

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

**2. Sign the finished file**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /a "dist\My App-Setup-1.0.0.exe"
```

**3. Verify**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
signtool verify /pa "dist\My App-Setup-1.0.0.exe"
```

**4. Write the update feed again**

Only if you use [`[updates]`](/docs/guides/updates). Signing changes the file's SHA-256.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach feed "dist\My App-Setup-1.0.0.exe" --url https://example.com/My%20App-Setup-1.0.0.exe
```

The signature is appended after Bach's payload and covers it, so any change to the file after signing breaks the signature.

## Let Bach sign (optional)

Signing is never required. If you would rather not run the signing tool yourself, add [`[signing]`](/docs/reference/config/signing) to `bach.toml` and build with `--sign`:

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[signing]
program = "signtool"      # the default
arguments = 'sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /a'
```

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

For `signtool` the arguments start with the word `sign`. Bach refuses them otherwise, because signtool answers "Invalid command". Bach then signs every setup file it writes (the offline installer, the online installer and an update patch) before it writes the update feed, so the feed already carries the signed file's SHA-256. Keep secrets out of `bach.toml` with `{env:NAME}` in the arguments. Bach prints the command first and fails the build when the signer fails.

> [!WARNING]
>
> Signing runs only when you ask for it with `--sign` or `BACH_SIGN=1`. A `bach.toml` that came from somewhere else can name any program, so building it never runs that program on its own.

`bach sign FILE` signs a file you built earlier in the same way. See [`bach sign`](/docs/reference/cli/sign).

## Notes

* **Sign after `bach build`, never before.** Building writes into the file. With `--sign`, Bach does it in that order for you.
* **The uninstaller is unsigned.** The `uninstall.exe` an install leaves behind is written on the user's computer from the signed setup file, without the signature, because a signature only covers the exact file it was made for.
* **Signing the setup file does not sign the programs inside it.** Windows 11's Smart App Control looks at every program that starts, so sign your own `.exe` and `.dll` files in your build, before Bach packs them. With `[signing]` in `bach.toml`, `bach check` and `bach build` warn when packed programs or libraries have no signature, and name the first three. Bach only reads the file's signature entry; Windows still decides whether it is valid. Without `[signing]` there is no warning, because you may not sign at all.
* **`bach inspect` reads signed setup files** too.
* **`bach doctor` reports whether the Windows SDK's `signtool` is found (on other systems `osslsigncode`; a program that only happens to be called `signtool`, like Mozilla's NSS tool on Linux, is not taken for it),** or that `[signing]` is set. Signing is optional.

## Why signing works

The payload sits before the signature's certificate table, so `signtool` signs a setup file like any other program and the signature covers the payload. See [How Bach works](/docs/concepts/how-it-works.md).

## Check a Bach download

Every file of a Bach release (the zip, `bach-setup.exe`, the example installer, the macOS and Linux downloads and the Windows ARM64 zip) has a signed statement from GitHub's artifact attestations: which commit and which workflow run built it. With the GitHub CLI:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
gh attestation verify bach-0.7.0-windows-x64.zip --repo usebach/bach
```

The release also lists what `bach` and `bach-setup.exe` are built from, as CycloneDX files: `bach-<version>-sbom-cli.cdx.json` and `bach-<version>-sbom-setup.cdx.json`. Each lists every crate with its version, licence and the checksum from `Cargo.lock`. The runtime's list is attached to `bach-setup.exe` as an attestation too. The `.sha256` files remain.

## Next steps

> [card] [Updates](/docs/guides/updates.md)
>
> Publish the signed file and the feed.

> [card] [winget](/docs/guides/winget.md)
>
> List the signed file in the Windows Package Manager.


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