Installing butler

The human-friendly way

You can download stable and bleeding-edge builds of butler from its itch.io page:

• https://itchio.itch.io/butler

Better yet, you can install it using theitch app, so it stays up-to-date.

The automation-friendly way

You can download the latest, bleeding-edge version of butler from broth:

• https://broth.itch.ovh/butler

broth is the download server used by the desktop app to install its own copy of butler.

The-head channels are bleeding-edge, the other ones are stable.

This is recommended if you need to install butler as part of a script, perhaps for continuous deployment

If you want to get the latest stable, for example, you could curl or wget the following URL:

• https://broth.itch.ovh/butler/linux-amd64/LATEST/archive/default

You can substitutelinux-amd64 with any channel listed on broth.

The file served is a .zip file, and this URL redirects to an expiring download URL. Here'san example bash script to install the latest stable butler for Linux:

# -L follows redirects# -O specifies output namecurl -L -o butler.zip https://broth.itch.ovh/butler/linux-amd64/LATEST/archive/defaultunzip butler.zip# GNU unzip tends to not set the executable bit even though it's set in the .zipchmod +x butler# just a sanity check run (and also helpful in case you're sharing CI logs)./butler -V

Note: the .zip file contains the butler executable, along with two dynamiclibraries related to 7-zip, which grant butler extra functionality. They'renot strictly required forbutler push, however, they shouldn't hurt either.

If you need help integrating butler in your CI pipeline, butler's GitHub issuetracker is a good place to ask:https://github.com/itchio/butler/issues/

Adding butler to your path

Adding an executable to your path allows you to launch it from anywhere,no matter which directory you're currently in.

On Windows

Follow this article to add the folder where you downloaded butler.exe to your path.

Alternatively, Windows will look into the current working directory whenlooking for commands

On Linux

If you extracted butler to a directory (let's say~/bin), you first needto mark it as executable. From a terminal, run:

chmod +x ~/bin/butler

(Replacing~/bin with the folder you actually want to store butler into)

Then, edit the~/.bashrc file (~ is your home directory) and add this lineat the end:

export PATH="$PATH:$HOME/bin"

(Again, replacing$HOME/bin as appropriate)

You'll need to close and start a new terminal to apply the changes. You shouldnow be able to move on to theFirst run section.

Alternatively, if you want to use the version installed by the itch app,you can skip the chmod command and use this line in your~/.bashrc instead:

export PATH="$PATH:$HOME/.config/itch/apps/butler"

On macOS

Follow the Linux instructions, except:

• On macOS, the~/.bash_profile file is used instead of~/.bashrc
  • You may have to create that file if it doesn't exist yet.
• If you want to use the itch app version, use this line in your~/.bash_profile instead:

export PATH="$PATH:$HOME/Library/Application Support/itch/apps/butler"

(don't forget the double-quotes, they're needed because there is a space in Application Support)

As with Linux, don't forget to close and re-open your terminal to apply the changes.

First run

To make sure butler is installed properly, open a terminal (cmd.exe on Windows),and type the following command:

butler -V

(that's a capital V, casing matters)

It should print something like that:

head, built on Sep 13 2018 @ 10:59:39, ref 30fe1c38a9611d6b17dc61c7d4fb9582aa369d41

Or if you're using a stable version,head will be replaced by asemantic versionnumber.

Here's how it looks on Windows:

Note: of course, you can also run butler from PowerShell. But if you knowabout PowerShell you probably didn't need to read most of this page anyway.

Appendix: Finding butler

If you ever forget where you put your butler.exe, thebutler which commandwill print its complete path.

Appendix: What happened to dl.itch.ovh ?

If you followed these instructions before September 2018, you might havedownload URLs starting withdl.itch.ovh. While new versions of butler arestill being deployed to that server for the time being, it is deprecatedand new CI setups should use the latestbroth.itch.ovh URLs instead.

dl.itch.ovh was a simple storage bucket with a proxy in front. It didthe job, but some users were unable to access it, and download speeds weresometimes suboptimal for non-US users.broth.itch.ovh serves downloadsthrough itch.io's CDN, which means every should have access and reasonabledownload speeds.

Additionally,dl.itch.ovh served "naked binaries", whereasbroth.itch.ovhnow serves .zip archives, because the full butler distribution is more thanone file. See the install instructions above for what these files are, andexample bash code on how to install butler from broth.