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 ). 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. → 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

1. Save as Draft (publish after verifying the first push).

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

Core command

butler push  /: --userversion 

| Argument | Example | Meaning | |----------|---------|---------| | ` | dist/ | local directory to upload | | / | acme/spacelander | itch.io target | | | html5 | upload channel (html5, windows, linux, osx, …) | | --userversion | 1.4.2` | stamps the upload (optional but recommended) |

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  /: [--userversion VER] [--ignore PATTERN]
butler status /[:]
butler fetch  /:    # download a build
butler validate                      # sanity-check a build dir
butler --version

Troubleshooting

| Symptom | Likely cause | Fix | |---------|--------------|-----| | butler: command not found | not installed | install per step 1 | | 404 Not found on first push | itch.io page doesn't exist | create the project page in browser first | | 401 Unauthorized | not logged in / bad API key | butler login, or fix BUTLER_API_KEY | | 403 Forbidden | account doesn't own the target | check / slug matches a project you own | | Push silently uploads everything every time | dist/ content non-deterministic (timestamps, build hashes) | rebuild with stable filenames, or --ignore volatile files | | --userversion shows up empty on itch.io | flag value missing/empty | confirm the version env / package.json field is set before invoking |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Yesterday-AI
• Source: Yesterday-AI/skills
• License: MIT
• Homepage: https://github.com/Yesterday-AI/skills

Install and usage instructions live in the source repository linked above.