“Butler” is the command-line utility for pushing game builds to itch.io. Here’s how you can use it to upload your game or project to itch.io.
Note: In all places where username is mentioned, you should use your account’s subdomain. Eg. if your URL is https://leafo.itch.io, you should use leafo. Generally your username and subdomain are the same, but they can differ. Subdomains are all lowercase and have no spaces.
-
Download & Install Butler: Butler can be installed on Windows, macOS, and Linux. You can download the latest version from the official itch.io page: https://itchio.itch.io/butler. Also review our guide for Setting Up Butler on Windows.
-
Authenticate Butler: In order for Butler to make changes to your account, you must authenticate it. The
butler logincommand is used. It will open a new browser window where you can log into your itch.io account and authorize Butler:butler login -
Push Your Game: Now, you’re ready to push your game. This is done by specifying the local directory of your game files, the itch.io username, the game’s page URL (you should have created this on itch.io), and the version (usually windows, osx, linux, or android). Here’s the syntax:
butler push /local/directory username/game:versionReplace
/local/directorywith the path to your game files on your local system,usernamewith your itch.io username,gamewith the name of your game as specified on your itch.io page, andversionwith the version you’re uploading.For example, if your username was “gamedev”, your game was “mygame”, the version you were uploading was for Windows, and your local directory was “C:/mygame/build”, you would use the following command:
butler push "C:/mygame/build" gamedev/mygame:windows -
Update Your Game: If you want to update your game later, you can simply push the updated build to the same channel name, and Butler will only upload the changed files, which can make updates much quicker.
Keep in mind that Butler is designed for uploading folders, so it can efficiently compress your files and generate patches. It is not necessary to pre-zip your project before calling the push command. If you tell Butler to push a zip file directly, it will extract the archive into a temporary folder on your computer before performing its operation.
Remember that Butler is a command-line tool, so you’ll need to be comfortable using the terminal or command prompt on your system. It also assumes that your game page is already set up on itch.io and that you’re logged into your account.
The documentation for Butler, which can provide more detailed information, can be found at this address: https://itch.io/docs/butler/
Troubleshooting Tips
Here are some common issues you might encounter when trying to use Butler, and how to solve them:
Incorrect Directory Path
If the directory path is incorrect, Butler will not find the game files, and the upload will fail. Make sure you are providing the correct path to the folder that contains your game files.
Solution: Double-check your directory path. On Windows, it often looks something like C:/Users/username/Documents/mygame, and on macOS or Linux, something like /Users/username/Documents/mygame. Make sure the directory contains all the necessary game files. You should provide the path to a folder, not file or list of files.
Spaces In Your Directory Path
File paths with spaces can sometimes cause problems because the command line interprets spaces as the end of an argument. For example, if you have a path like C:\Path\To\My Game Files\, the command line could interpret this as two separate paths: C:\Path\To\My and Game Files\, which would lead to an error.
Solution: Quote Your File Paths: You can usually solve this issue by enclosing your file paths in quotes. This tells the command line to treat everything within the quotes as a single argument, even if it includes spaces. So, if the path to your game’s files was C:\Path\To\My Game Files\, you would enter it as "C:\Path\To\My Game Files\". Here’s how the complete command might look:
butler push "C:\Path\To\My Game Files\" username/game:version
This will instruct Butler to treat the entire quoted string as a single path, allowing it to correctly find your files even if the path includes spaces. As a best practice, it’s a good idea to always quote your file paths when using the command line to avoid issues with spaces or other special characters.
Remember to replace C:\Path\To\My Game Files\ with the actual path to your project’s files, and username/game:version with your itch.io username, your project’s name, and the version you’re uploading.
Incorrect Project Name or Username
If you enter the wrong username or project name when pushing, Butler will not know where to upload the files. The project name should be the same as on the project page URL on itch.io, and the username should be your itch.io subdomain.
If Butler can not find an account or project it will return an error like:
itch.io API error (400): /wharf/builds: invalid target (bad user)itch.io API error (400): /wharf/builds: invalid target (bad game).
Solution: Double-check the username and project name you’re using. The command should be in this format: butler push /path/to/gamefiles username/game:channel. The username should be the part of your itch.io’s URL before itch.io. If yo
Forgot to Authenticate
If you haven’t authenticated Butler with butler login, then it won’t have permission to upload to your itch.io account.
Solution: Authenticate by running the command butler login and follow the instructions.
Did Not Set up the Project Page First
Butler does not create a new project page for you; it assumes you have already created one.
Solution: Ensure that you have set up your project page on itch.io.
Firewall or Antivirus Interference
In some cases, your antivirus software or firewall might prevent Butler from uploading files.
Solution: If you suspect this is the problem, try temporarily disabling your antivirus or firewall to see if that solves the problem. If it does, you will need to add an exception for Butler.
Remember to check the error messages that Butler provides if something goes wrong. These can often give you clues about what you need to fix. If you’re having trouble understanding an error message, the Butler documentation or itch.io community forums might be able to provide more information.