repository·master·Indexed 21 days ago
https://github.com/itchio/butlerThe official command-line toolset for itch.io, used by creators for uploading builds and by the itch app for patching and filesystem operations. Includes documentation for the butler daemon (butlerd), covering TCP and Stdio transports, JSON-RPC 2.0 communication, profile management, game fetching, and lifecycle control via Meta.Flow and Meta.Shutdown.
butlerd is a JSON-RPC 2.0 service designed to handle butler tasks. It is used to manage either long-running tasks (referred to as operations) or individual one-off requests.
It supports two transport mechanisms:
butler is the official itch.io command-line tool designed for managing game builds. It provides a reliable way to:
While butler is a CLI tool, users who prefer a graphical interface can use the itch app (v26.12.0 or later), which includes a built-in interface for pushing builds, viewing change previews, and managing builds via the 'Builds' page in the sidebar.
Butler uses the channel name to automatically tag builds with platform metadata. While you can manually override these tags on the itch.io Edit game page, using specific keywords in your channel name helps automate the process.
Platform Keywords:
win or windows $\rightarrow$ Windows executablelinux $\rightarrow$ Linux executablemac or osx $\rightarrow$ Mac executableandroid $\rightarrow$ Android applicationConventions:
kebab-case (lowercase with dashes).win-linux-mac-stable).When performing a Publish.Push, butlerd emits several notifications to allow clients to track the operation's lifecycle and progress.
Publish.Push.BuildAssigned: Emitted once as soon as the worker obtains a build ID from the itch.io API (after CreateBuild succeeds but before data flows). Use this to associate your in-flight push with the server-side build ID.Publish.Push.BuildFailed: Emitted if the push errors out after a build was assigned and the worker successfully marked the build as failed on the server. This allows updating local views to "failed" without polling.Publish.Push.Progress: Periodic updates emitted while the push is in flight.| Field | Type | Description |
|---|---|---|
progress | number | 0..1; conservative estimate based on uploaded vs source size |
eta | number | Estimated seconds remaining (0 if unknown). Refers to the upload phase |
bps | number | Upload bytes per second (wire throughput, not disk read speed) |
readBytes | number | Bytes read from the source container so far while computing the patch |
totalBytes | number | Total bytes in the source container |
uploadedBytes | number | Bytes of the patch uploaded to itch.io so far |
patchBytes | number | Compressed patch size produced so far. Equals uploadedBytes once upload catches up |
butler push or butler status. If a newer version is available, a notice will be displayed in your terminal.A Manifest describes prerequisites (dependencies) and actions that can be taken while launching a game.
struct Manifest {
actions: Actions; // List of options to give the user when launching a game
prereqs?: Prereq[]; // Libraries or frameworks that must be installed prior to launching
}When building a launcher, keep these technical constraints in mind:
data.apiError object containing a statusCode and a messages array. These messages are human-readable and intended to be shown directly in your UI.butlerd is single-tenant and expects exactly one client. If your application has multiple windows or processes, multiplex them through a single connection/daemon. Never spawn multiple daemons against the same --dbpath.id. To abort an operation, call the corresponding *.Cancel method using that same id.In butlerd, every installation is represented as a cave. A cave is a unique record of an installation.
Cave Properties:
caveId: A unique UUID.last-played timestamp, and total seconds run.One game can have multiple caves (e.g., different versions or different install locations). Most launchers use Fetch.Caves filtered by gameId to determine if a game is installed and show its status.
Butler handles large bundles (containing thousands of games) using a two-stage ownership model to prevent database bloat. Instead of creating a DownloadKey for every game at the time of purchase, ownership is managed via a BundleKey.
BundleKey per bundle purchase. The individual games inside the bundle are not yet DownloadKey rows in the database.DownloadKey is only created (minted) when the user actually attempts to install a specific game from that bundle. This is triggered by the ClaimBundleGame operation.DownloadKey exists, allowing the UI to show "Install" instead of "Buy now."A robust butlerd client must handle three types of JSON-RPC messages:
id and await the response with the same id.id) used to report progress on long-running operations.butlerd may send a request to the client. The client must be able to receive these requests and send back a response object.Implementation Pattern: Model your client with three components:
await responses by id.method).method) that returns a response.To maintain performance and avoid massive memory footprints, the renderer should follow these patterns for bundle ownership:
Fetch.Commons for bundles: Do not add the entire bundle ownership set to the global Commons object. Commons should remain focused on small, global state like materialized download keys and caves.Fetch.GameOwnership for game pages: On direct game pages, layer Fetch.GameOwnership on top of existing game status. This allows a bundle-owned game to show an 'Install' button without requiring the entire library to be loaded into memory.Fetch.BundleGames for bundle pages: When viewing a bundle detail page, use the paginated Fetch.BundleGames endpoint to show its contents.Fetch.GameOwnership returns Stale: true, the renderer should trigger a background sync via Fetch.ProfileBundleOwnerships(fresh: true). This should be debounced and avoided on high-frequency UI elements like search inputs or list hovers.When the itch app calls Launch, butlerd orchestrates a multi-phase flow including target selection, prerequisites, sandbox setup, and game execution. The communication between the client (itch app) and butlerd uses two types of messages:
Understanding this flow is essential for implementing a client that can correctly handle game launches, license agreements, and prerequisite installations managed by butlerd.