Using butler to Upload itch.io Builds in One Command
We shipped a jam game last spring and then spent two days patching it. Each patch meant zipping the export folder, opening the itch.io dashboard, waiting for a 180 MB upload over home internet, and renaming the file so players could tell...

We shipped a jam game last spring and then spent two days patching it. Each patch meant zipping the export folder, opening the itch.io dashboard, waiting for a 180 MB upload over home internet, and renaming the file so players could tell which build they had. By the fourth round I had uploaded the wrong folder once and overwritten the Windows build with the web build once. Nobody complained publicly, which is worse than complaining, because they just closed the tab.
Then a player in our Discord asked why the itch app was not offering him an update. That is when I learned about butler, the command line uploader itch.io maintains, and about channels, which are the thing that makes auto updates work at all. One command now replaces all of it, and a patch upload that used to take 20 minutes takes about 40 seconds. Here is the setup we use, including the parts the official docs mention once and the mistakes that cost us a release night.
What butler does that the upload form cannot
butler does not just move a zip file faster. It diffs your build against the version already on itch.io and uploads only the changed blocks. For a Godot export where the pck file changes but the 60 MB of bundled runtime does not, that difference is enormous. Our last patch pushed 2.3 MB instead of 184 MB.
The second thing it does is write to a named channel instead of to a file. A channel is a slot with a name like windows-beta that keeps its history. The itch desktop app watches channels, so when you push a new build to the same channel, players who installed through the app get the update without touching anything. Drag and drop uploads create a new file each time and break that chain.
The third thing, and the one I underrated, is that butler takes a folder. You stop zipping. Your export directory goes up as it is, which removes the whole class of errors where you zipped the parent folder and players ended up with a game inside a folder inside a folder.
Setting up butler in about ten minutes
You need an itch.io account, a project page that already exists, and a terminal. The project page can be draft or restricted, it does not need to be public.
- Download butler for your platform from the itch.io page for it and put the binary somewhere on your PATH. On Windows I keep it in a tools folder next to the project and add that folder to PATH, so new team members get it with the repo.
- Run butler login. It opens a browser, you approve, and the key is saved to your user profile. You do this once per machine.
- Export your game into a clean folder. Clean matters. Our first push included a 400 MB folder of source PSD files because they lived in the export directory.
- Push with butler push build/windows foxstudios/our-game:windows. The part after the colon is the channel name, and you invent it.
- Run butler status foxstudios/our-game to confirm. It lists each channel, the build number, and whether itch.io finished processing it.
That is the whole loop. From then on, a patch is one command with the same channel name.
Channel names matter more than they look
itch.io reads platform information out of the channel name, which is undocumented enough that most people get it wrong once. Include the platform word and it tags the upload automatically. The names we settled on:
- windows for the 64 bit desktop build. Adding the word windows is what makes the Windows icon appear on the page.
- linux and osx for the other two desktop targets. Use osx, not mac, because mac is not one of the words it recognises.
- html5 or web for the browser build. This one has a hard requirement: index.html must sit at the root of the folder you push, not inside a subfolder.
- windows-demo for a cut down build. Anything after the platform word is yours to use, and it creates a separate slot that does not disturb the main one.
Pick the names before your first push. Renaming a channel later means the old one sits there as an orphan, and players who installed from it stop getting updates without any message telling them why.
The flag I wish I had used from the start
Add the userversion flag to every push. Without it, builds are identified only by an incrementing number that means nothing to you, and when a player says "I am on build 14 and the save is corrupt" you have no idea which commit that was.
We pass the git short hash and the date, something like 0.4.2-a91f3c. It shows up in butler status and in the itch app's install details, so a bug report arrives with the exact build attached. That one habit has saved more debugging time than any other change in our release process. It also catches the case where you push the same folder twice by accident, because butler reports zero changed blocks and you know immediately.
The counter-take: skip the CI pipeline for now
Every thread about butler ends with somebody recommending a GitHub Actions workflow that exports and pushes on each tag. It looks like the professional answer, and for a team of eight shipping monthly it is. For a two person studio it is usually a trap, and I say that as the person who built ours and then deleted it.
The problems were small and constant. Headless engine exports need the export templates installed in the runner, which meant a 1.2 GB download on every run until I cached it, and the cache expired weekly. Our API key sat in repository secrets, which is fine until a collaborator forks the repo and the workflow fails in a way that looks like a butler problem. Then the runner pushed a broken build at 2 in the morning because a tag was pushed from a branch that did not compile, and the itch app cheerfully delivered it to everyone.
A human running one command after looking at the game once is slower and considerably safer. Set up CI when the release process is boring enough that you resent doing it, not before. The release checklist we use is the version of this that actually catches mistakes, because it makes you look at the build.
Things that will bite you once
Pushing a folder that contains a .git directory uploads your whole history to the game page. Check with a dry run push, which butler supports through its own flag, before the first push of a new target.
Deleting a channel does not delete the builds, and the storage still counts. If you experiment with names, clean up through the dashboard afterwards.
The web build cache is aggressive. After pushing to an html5 channel the page can serve the old version for several minutes, which has made me re-push twice for nothing. Wait, then hard reload before you decide something is broken.
Finally, record the result. A short clip of the new build running is worth more than a changelog line, and the notes on devlog GIFs and short clips cover how to capture one in a couple of minutes. The rest of what we use day to day is in the tools section.
FAQ
Does butler work with Scratch projects?
Not directly, because Scratch hosts the project itself. If you export a Scratch project to HTML with a packager, the resulting folder pushes to an html5 channel like any other web build, as long as index.html is at the root.
Is butler free?
Yes, and so is the storage for normal game builds. itch.io has no published hard cap for build storage, though very large projects have been asked to tidy up old channels, so do not keep 40 dead slots around.
Can I use butler with a draft page?
Yes. Push to a draft or restricted project and only you and invited people can download it. This is the easiest way to hand a build to three playtesters without publishing anything.
What happens if two of us push at once?
The second push wins and becomes the current build. There is no lock. We avoided one bad overlap by agreeing that whoever says "pushing now" in the channel owns the next five minutes.
More in Tools
Tools
Running Godot 4 on a Low Spec School Laptop Without Lag
Nine of the fourteen laptops in the Tuesday class I teach are the same kind of machine: a four or five year old 14 inch model,...
Tools
Devlog GIF Capture Tools and How to Shrink the Files
The best clip we ever recorded was six seconds of a boss slamming into a wall and dropping its shield, and almost nobody saw it...
Tools
How to Use a Kanban Board for Game Development
Six months into our second game, we had a 300 line to do list in a text file, three people working from different versions of...