Skip to content
usebachPublic

About

Modern, clean Windows installers from one bach.toml.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

8 stars

Watchers

0 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Latest commit

 

History

340 Commits

Folders and files

Repository files navigation

Bach logo

Bach

One bach.toml in, one Setup.exe out.
Windows installers with a native window, in-place updates and a clean uninstaller,
without an installer script and without an administrator prompt.

CI status Latest release MIT license

Quickstart · Docs · Config reference · Releases · Changelog

Bach's install window in light mode: install location, a sample-notes component, desktop shortcut and start-with-Windows options, Cancel and Install buttons The same install window in dark mode

Bach packs the folder your app builds into, plus a short config file, into a single setup file. Your users get one calm window in their own language; you get updates over older installs and an uninstaller in Settings › Apps, without writing installer logic.

Quick start

Install the bach command (Windows, macOS and Linux; Node.js 18 or newer; no Rust, no administrator rights):

npm install --global @usebach/cli

No Node.js? Other ways to install has a one-line script for each system, Scoop, a GitHub Action and a zip file.

Then, in your project:

bach init      # writes a commented bach.toml (and, on GitHub, a release workflow)
bach check     # validates it and lists every file the installer will carry
bach preview   # opens the real window; nothing is installed
bach build     # writes the setup file

A complete config for a Rust app:

# bach.toml
[app]
name = "Hello"
version = "1.0.0"
publisher = "Hello Inc."
executable = "hello.exe"

[files]
source = "target/release"
exclude = ["*.pdb", "deps/**", "build/**"]
$ bach build
Wrote dist\Hello-Setup-1.0.0.exe (9.7 MB)
  Packed       101.8 KB of 216.5 KB (47%), in 0.9s

examples/hello is a working project to try it on, and getting started walks through it step by step. In a GitHub repository, bach init also adds a one-click release: commit it, then press Actions › Release › Run workflow (releasing).

Why Bach

NSIS, Inno Setup and WiX can build almost any installer, and ask you to learn a scripting language or an XML schema to do it. Bach covers the common case, an app that installs for one user, with settings instead of code:

  • No script. Everything is a setting in one TOML file with an editor schema. Every mistake is reported as one sentence naming the setting at fault.
  • No admin prompt unless you want one. Apps install per user into %LOCALAPPDATA%\Programs and only write to the user's own folders and HKCU. For every user of a computer, scope = "machine" installs into %ProgramFiles% after one Windows prompt.
  • Updates that can't half-fail. A newer setup file updates an install in place: files are unpacked first and swapped in together, and if one is locked, everything is put back. Files the new version no longer ships are removed.
  • A window people can read. 19 languages built in, following the Windows display language; light and dark mode (and Windows contrast themes); every text replaceable; every choice reachable with Tab.
  • Builds anywhere. bach runs on Windows, macOS and Linux, so installers can come out of any CI. Setup files need no .NET and no Visual C++ runtime.

Use something else when you need drivers, custom install-time scripts, or a small stub: a Bach setup file adds about 10 MB to your app. For Group Policy and Intune, bach build --msi also writes a Windows Installer package.

What setup files can do

Choices Desktop and Start menu shortcuts, start with Windows, add to PATH, each offered ticked, unticked, always or never; optional components, even ones downloaded when ticked
Integration myapp:// link schemes, file types and right-click entries, never taking over another app's; Windows services and firewall rules for machine-wide installs
Look and words 14 built-in styles (soft gradients, terminal, game looks, ...) and 10 layouts, or your own fonts, colours, corners, pictures, logo and icon; light, dark or system theme; any text, per language; a license page
Safety Free-space check, archive checksum, one setup per app at a time, "close and continue" when the app is open, data deleted only on request
Updates Over older installs always; by themselves in the background from GitHub releases (or any https feed, optionally signed), installed when the app is closed, undone cleanly if a power cut interrupts them; patches with only the changed files. See updates
Automation Setup.exe /S with --dir, --with, --without, --log; quiet uninstall from Settings › Apps
Deployment An online installer that always downloads the newest version; access keys that encrypt the files and keep updates private; an ARM64 build next to x64; profiles (a portable ZIP, a company version); an .msi; winget, Chocolatey and Intune output

Every setting is in the config reference.

Commands

Command What it does
bach import Writes a first bach.toml from an Inno Setup or NSIS script, and lists what it couldn't convert
bach init Writes a starter bach.toml, filled in for Rust, Tauri, Electron, .NET, Godot and Unity projects, plus a release workflow in a GitHub checkout
bach check Validates the config and lists every file and option; --strict turns a warning into an error
bach preview Opens the real window without installing; try --theme dark, --lang de, --style arcade, --layout showcase
bach watch Like preview, and reopens the window every time you save bach.toml
bach build Writes the setup file; --online, --msi, --patch-from OLD.exe, --profile NAME, --sign and more
bach styles, bach layouts List the built-in styles and layouts
bach inspect, bach verify, bach diff Show what a setup file carries, check it for damage, compare two versions
bach test Installs, starts and removes a setup file in Windows Sandbox (or, with --here, on a CI runner) and reports what failed or was left behind
bach sign, bach key, bach feed-key Sign a setup file, make access keys, make the key that signs update feeds
bach feed, bach page, bach winget, bach choco, bach intune Write the update feed, a download page, and the winget, Chocolatey and Intune packages
bach version, bach workflow Raise the version in every file at once; add the one-click release workflow
bach doctor, bach update Check that a build can run; update bach itself

Run bach on its own for this list grouped by what you are doing, and bach COMMAND --help for the options of one command. Every flag is in the CLI reference.

Other ways to install

  • PowerShell (installs to %LOCALAPPDATA%\Programs\bach-cli and adds it to PATH):

    irm https://raw.githubusercontent.com/usebach/bach/main/install.ps1 | iex
  • macOS or Linux, for building Windows installers in CI:

    curl -fsSL https://raw.githubusercontent.com/usebach/bach/main/install.sh | sh
  • Scoop: scoop install https://raw.githubusercontent.com/usebach/bach/main/scoop/bach.json

  • npm also works per project (--save-dev, then npx bach).

  • By hand: download bach-<version>-windows-x64.zip from releases and keep bach.exe and bach-setup.exe together.

  • GitHub Actions, on any runner. This builds and publishes a release for every pushed tag like v1.4.0; the tag is the app's version, and installed apps update from it (updates):

    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      # ... build your app ...
      - uses: usebach/bach@v0
        with:
          config: bach.toml
          release: true

    Leave out release: true to only build; the file's path is the step's setup output. @v0 follows the newest 0.x release, @v0.2 the newest 0.2.x, @v0.2.1 never moves.

The install scripts install per user and never ask for administrator rights; the install docs cover a system-wide install. bach update keeps bach current: it checks the SHA-256 published next to each release and puts the old files back if a step fails. A bach installed by npm, Scoop, winget or Cargo is updated by that tool, and bach update names the command. BACH_NO_UPDATE_CHECK=1 turns the notice off.

Coding agents can learn all of this from skills/bach/SKILL.md (npx skills add usebach/bach).

Project status

Bach is pre-1.0 and released often; every release is in the changelog. Setup files keep working across releases: the payload format changes only with a new format version and a clear error for the old one. How it works explains the file format and the safety rules, and the threat model says what Bach does and does not protect against.

Build from source

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

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. AGENTS.md covers the code layout, checks and conventions.

Contributing

Bug reports, translations and pull requests are welcome; start with CONTRIBUTING.md. Questions go to SUPPORT.md, security problems to the security policy, and everyone here follows the Code of Conduct.

License

MIT

About

Modern, clean Windows installers from one bach.toml.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

8 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages