Butler Deploy

Butler Deploy

Push HTML5 game builds to itch.io with the butler CLI. Butler does delta uploads (only changed files after the first push) and the game is live the moment the push completes.

When to use

• First-time publish of a web build to itch.io
• Updating an existing itch.io page with a new build
• Wiring an itch.io deploy step into CI

Prerequisites

1. Install butler (one-time, per machine)

# macOS
brew install butler

# Linux
curl -L -o butler.zip https://broth.itch.ovh/butler/linux-amd64/LATEST/archive/default
unzip butler.zip
mv butler /usr/local/bin/butler

# Windows
scoop install butler
# or download from https://itchio.itch.io/butler

2. Authenticate (one-time, per machine)

butler login
# Opens browser → authorize → return to terminal.

For CI: set BUTLER_API_KEY instead (generate at https://itch.io/user/settings/api-keys). No butler login needed.

3. Create the itch.io page (one-time, in browser)

Butler refuses the first push if the target page does not exist.

1. https://itch.io/dashboard → Create new project
2. Settings:
   • Kind: HTML
   • Viewport size: match your build (e.g. 1280×720)
   • "This file will be played in the browser": checked
3. Save as Draft (publish after verifying the first push).

After the page exists, all future deploys are fully scripted.

Core command

butler push <build-dir> <user>/<game>:<channel> --userversion <version>

Example:

butler push dist/ acme/spacelander:html5 --userversion 1.4.2

Common patterns

Build then push

Wire build + push together — pick whichever fits your stack:

# Direct
npm run build && butler push dist/ acme/spacelander:html5 --userversion "$(node -p "require('./package.json').version")"

# Make
make build && butler push build/web acme/spacelander:html5

# Project npm script (optional convenience)
# package.json: "deploy": "butler push dist/ $ITCH_GAME:html5 --userversion $npm_package_version"
ITCH_GAME=acme/spacelander npm run deploy

Channel-per-platform

butler push dist/web    acme/spacelander:html5
butler push dist/win    acme/spacelander:windows
butler push dist/linux  acme/spacelander:linux
butler push dist/osx    acme/spacelander:osx

Verify after push

butler status acme/spacelander            # all channels, latest version + state
butler status acme/spacelander:html5      # one channel

Useful butler commands

butler login                              # interactive auth (browser)
butler logout
butler push <dir> <user>/<game>:<channel> [--userversion VER] [--ignore PATTERN]
butler status <user>/<game>[:<channel>]
butler fetch  <user>/<game>:<channel> <out-dir>   # download a build
butler validate <dir>                     # sanity-check a build dir
butler --version

Troubleshooting