Indie game storeFree gamesFun gamesHorror games
Game developmentAssetsComics
SalesBundles
Jobs
Tags

How to upload your game or project to itch.io with butler Sticky

A topic by leafo created May 22, 2023 Views: 3,666 Replies: 3
Viewing posts 1 to 4
Admin (18 edits) (+4)

“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.

  1. 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.

  2. Authenticate Butler: In order for Butler to make changes to your account, you must authenticate it. The butler login command is used. It will open a new browser window where you can log into your itch.io account and authorize Butler:

    butler login
    
  3. 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:version
    

    Replace /local/directory with the path to your game files on your local system, username with your itch.io username, game with the name of your game as specified on your itch.io page, and version with 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
    
  4. 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.

Admin (2 edits) (+2)

Setting up Butler on Windows

Using the itch.io app

If you have the itch app installed on your Windows computer, it comes bundled with Butler. We recommend using this version as it will automatically be updated if you use the itch.io app. Here’s how to configure your system to use this version of Butler:

  1. Locate Butler’s executable: First, you need to locate where the itch app is installed. By default, the itch app is installed in the %APPDATA%/itch folder. Inside that, you will find the Butler executable in apps/butler.

  2. Add Butler to PATH: After locating the Butler executable, you need to add it to your system’s PATH so you can run it from any command prompt. Here’s how:

    • Press Win + X and choose System.
    • Click on Advanced system settings.
    • Click on Environment Variables.
    • Under System variables, find and select Path, then click on Edit.
    • Click on New and then add the path where Butler is located, e.g., %APPDATA%\itch\apps\butler.
    • Click OK on all windows to save the changes.
  3. Open Command Prompt: Press Win + R, type cmd, and hit Enter to open the Command Prompt.

  4. Authenticate Butler: In the Command Prompt, type butler login and hit Enter. This will open a new browser window where you can log in to your itch.io account and allow Butler to access your account.

Your computer is now ready to use Butler from the Command Prompt.

Manual Install

If you don’t with to use the itch.io app or you want to manually manage the version of Butler you use, you can follow the following instructions to install it:

  1. Download Butler: First, you need to download Butler. You can get the Windows version of Butler from the following URL: https://itch.io/docs/butler/installing.html

  2. Install Butler: After downloading, you’ll get a .zip file. Extract it to a location of your choice. For the sake of simplicity, let’s say you extract it to C:\butler.

  3. Add Butler to PATH: Next, you need to add Butler to your system’s PATH so you can run it from any command prompt. Here’s how:

    • Press Win + X and choose System.
    • Click on Advanced system settings.
    • Click on Environment Variables.
    • Under System variables, find and select Path, then click on Edit.
    • Click on New and then add the path where you extracted Butler, e.g., C:\butler.
    • Click OK on all windows to save the changes.
  4. Open Command Prompt: Press Win + R, type cmd, and hit Enter to open the Command Prompt.

  5. Authenticate Butler: In the Command Prompt, type butler login and hit Enter. This will open a new browser window where you can log in to your itch.io account and allow Butler to access your account.

Your computer is now ready to use Butler from the Command Prompt.

(+1)

I’m not using it yet but I have done a bit of research and love that you’ve got solid development tools like this and really make it easy to understand how to start using them. Appreciate all the work! 👏

No matter what I type at the command line, it starts a textbased wizard and finally asks for a "description I wanna parse" but that is not anywhere in your documentation.