butler: the itch.io command line tool behind build pushes and delta patches

Two audiences share one binary: creators and the itch app

butler is described as the itch.io command line tools, and the project names two users of it. The first is content creators on itch.io, who use it to push builds quickly and reliably. The second is the itch app itself, which links the same code for some network, filesystem and patching operations.

That second audience explains the shape of the repository. A creator who only wants to upload a build needs a command line tool, while a desktop application needs a library it can call into and a daemon it can talk to. butler is built as both, and the same Go code sits behind either entry point.

The topic tags on the repository are also revealing: deployment, game-development, itchio, rsync and bsdiff. The last two name the actual transport and patch formats, which tells you that this is not a thin wrapper over an upload form but a tool that moves bytes intelligently between your machine and the platform.

hush, wharf and boar carry the actual work

The architecture diagram makes it clear that butler is not one program but a hub with a long tail of dependencies, and the README calls this a somewhat complicated collection of sub-packages. Four sit at the high level: hush, wharf, boar and go-itchio. Two more, savior and httpkit, sit in the middle, and below them are leaf packages for specific jobs.

The four high level packages map onto distinct phases of a push. go-itchio is the itch.io API client library, so it is the layer that talks to the platform. hush handles installation receipts and manifests, which is how a build records what it contains. wharf covers delta patching, binary diffing and the pwr format, so it is the piece that makes updates small. boar handles multi-format archive extraction for 7z, RAR and ZIP.

If you are evaluating whether to build on butler, this is the part that matters. The useful logic is not in the butler repository, it is in these sibling repositories, and each has its own release cycle and its own changelog.

Delta patching through wharf is why pushes stay small

Shipping a new build of a game means shipping files that mostly did not change, and butler treats that as a first class problem rather than a nice to have. wharf is the package for delta patching and binary diffing, and it works in the pwr format. The bsdiff topic tag points at the same idea from the compression side, where a binary diff is applied to an existing copy to produce a small patch.

The practical effect is on the upload side of a deployment. A creator pushing a 2 GB build does not re-upload 2 GB each time, and the itch app, which uses butler for patching operations, gets the same benefit when it updates an installed game. The README does not document the patch format itself, the size ratios involved, or the fallback behaviour when a patch cannot be applied, so the fine print lives outside this repository.

The other end of that flow is the lake package, which handles binary storage pools and file structure tracking, so the patched result still lands in a place the platform understands.

Building from source means Go 1.25.0 and CGO enabled

There is no package on a language registry to install; butler is distributed as versioned releases and its documentation lives at itch.io/docs/butler, with a bleeding edge version published at itchio.github.io/butler. To build the binary yourself, the Makefile in the repository root is the entry point.

The module declaration in go.mod pins the language version the code expects:

module github.com/itchio/butler

go 1.25.0

The build target compiles with CGO enabled and stamps version information into a buildinfo package, so the binary records its own version, commit and build time:

CGO_ENABLED=1 go build -ldflags "$(LDFLAGS)" -o butler .

The install target does the same thing but places the result on your Go path, and the test target runs the suite with the race detector and coverage:

CGO_ENABLED=1 go install -ldflags "$(LDFLAGS)" .

go test -v -race -cover ./...

CGO is a hard requirement of that Makefile rather than a preference, which on a machine without a C toolchain means the build stops before it starts. There is also a generous target that runs godocs generation from the butlerd directory, which is a hint that the daemon's API is treated as a published interface.

butlerd exists as a separate daemon with its own API

The repository carries a butlerd/ directory at its top level, next to cmd/, manager/, endpoints/, steam/, shell/ and win32/. The README points at separate API documentation for the butlerd daemon at itchio.github.io/butler/butlerd/, labelled as bleeding edge, alongside the main documentation at itch.io/docs/butler and the bleeding edge documentation for the command line tool at itchio.github.io/butler.

So the tool ships in two shapes. The command line tool does the obvious work of pushing a build. The daemon exists so that a long lived process, such as the itch app, can ask for work over an API instead of spawning the tool for every operation. The split is what lets the desktop client reuse the same filesystem, network and patching code that a creator runs from a shell.

The cost is documentation drift. Two documentation sets exist, one stable and one bleeding edge, and the daemon API has its own separate page. Anything you build against butlerd is building against the bleeding edge surface, and the README does not state a version guarantee for it.

Archive extraction leans on libc7zip and a RAR binding

The package list shows how much of butler is really about handling other people's file formats. boar handles multi-format archive extraction for 7z, RAR and ZIP, and it depends on sevenzip-go, which binds the 7-zip library, and dmcunrar-go, which handles RAR decompression. sevenzip-go in turn links dynamically against libc7zip, a C wrapper for 7-zip that lives in its own repository.

Alongside that, the compression side runs through kompress, an abstraction layer over dskompress, go-brotli and lzma, plus randsource for random source utilities. The leaf packages cover the rest of the practical surface: arkive for ZIP and archive format support, dash for game configuration, metadata and executable probing on ELF and PE, pelican for parsing Windows PE binaries, smaug for Windows installer and runtime detection, spellbook for file magic number detection, ox for OS abstractions such as registry access and system calls, and hades for SQLite schema and queries.

Two of those deserve a warning. dash probes executables and pelican parses PE binaries, so behaviour on an unfamiliar platform depends on how well those probes know your build format. And ox touches the Windows registry, which is the kind of thing that makes butler awkward to run inside a locked down container.

Fifteen point releases a year, with a busy repository

butler moves fast. The recent release list shows v15.32.0 on 2026-10-06, v15.31.0 on 2026-09-01 and v15.30.0 on 2026-07-27, which is a steady drum of minor version bumps, and the last push to the repository was on 2026-10-19. The project is MIT licensed, so the code can be reused in commercial tooling as long as the copyright and licence notice are kept.

That cadence cuts both ways for an adopter. A new release every few weeks means fixes arrive, but it also means the go.mod file points at sibling packages pinned to specific commit hashes, several of which are dated within days of each other. Upgrading butler can pull in new versions of hush, wharf, boar, dash and more, and the version numbers of those dependencies do not follow the same scheme.

There is also a JavaScript file in the root, package.json, describing a package named @itchio/butler that declares the itch.io command line tool as its description, with devDependencies on @itchio/bob and @types/node. The test script in it is a placeholder that exits with an error, which tells you the JavaScript side is tooling for the Go project rather than a second implementation.

Editorial conclusion

butler is the right tool if you publish to itch.io, because the hush, wharf and boar packages behind its push command are not reimplemented anywhere else, and its MIT licence lets you embed the same code in a launcher. It is the wrong tool if you need to push to another storefront, or if you want a small standalone binary, since the source tree expects Go 1.25.0 with CGO enabled and a buildinfo stamp. Before adopting it, read the release notes for the version you pin, since v15.32.0 landed on 2026-10-06 and the tree changes often.

Frequently asked questions

Official sources

1. Issues
2. itchio/butler on GitHub
3. License: MIT
4. README
5. Releases