butler

https://itch.io/docs/butler/
Admin
butler is a command-line tool for uploading game builds to itch.io, generating patches, and applying...
Tokens:37,274
Snippets:273
Trust Score:9.9
Update:6 days ago
Show doc for...
Tokens:
Raw
### Expected output of butler version

Source: https://itch.io/docs/butler/installing.html

Example output when butler is installed correctly. The version and build details may vary.

```text
v15.24.0, built on Dec 12 2024 @ 17:12:35, ref f1203f79c4b65ef2201e95ca81b6b02b7d37cb04

```

--------------------------------

### Install.Queue

Source: https://itch.io/docs/butler/launcher-integration.html

Queues an install by specifying the game, upload, optional build, install location ID, and reason. Returns a task UUID and staging folder.

```APIDOC
## Install.Queue

### Description
Queues an install by specifying the game, upload, optional build, install location ID, and reason. Returns a task UUID and staging folder.

### Method
RPC

### Parameters
- **game** (object) - Required - The chosen game.
- **upload** (object) - Required - The chosen upload.
- **build** (object) - Optional - The build for wharf channels.
- **installLocationId** (string) - Required - The ID of the install location.
- **reason** (string) - Required - One of: `install`, `update`, `reinstall`, `version-switch`.
- **queueDownload** (boolean) - Optional - If true, butlerd manages the actual download.

### Response
- **taskId** (string) - The task UUID.
- **stagingFolder** (string) - The staging folder path.
```

--------------------------------

### Install.PlanUpload

Source: https://itch.io/docs/butler/launcher-integration.html

Computes disk space needed and detects installer type for a queued install. Recommended before performing.

```APIDOC
## Install.PlanUpload

### Description
Computes disk space needed and detects installer type for a queued install. Recommended before performing.

### Method
RPC

### Parameters
- **taskId** (string) - Required - The task ID from the queue step.

### Response
- **diskSpaceNeeded** (number) - The amount of disk space required.
- **installerType** (string) - The detected installer type.
```

--------------------------------

### Fetch.GameUploads

Source: https://itch.io/docs/butler/launcher-integration.html

Fetches game uploads for installation. Called with compatible:true when the user clicks install.

```APIDOC
## Fetch.GameUploads

### Description
Fetches game uploads for installation. Called with compatible:true when the user clicks install.

### Method
CALL

### Endpoint
Fetch.GameUploads

### Parameters
#### Request Body
- **compatible** (boolean) - Optional - Whether to only fetch compatible uploads. Default false.

### Response
#### Success Response
- No specific response fields documented.

```

--------------------------------

### Install.Queue

Source: https://itch.io/docs/butler/launcher-integration.html

Queues an installation or update. Pass the existing caveId and reason "update" to apply an update. This is part of the Install flow used for fresh installs and updates.

```APIDOC
## Install.Queue

### Description
Queues an installation or update. Pass the existing caveId and reason "update" to apply an update. This is part of the Install flow used for fresh installs and updates.

### Method
CALL

### Endpoint
Install.Queue

### Parameters
#### Request Body
- **caveId** (string) - Optional - The cave ID of the existing installation when applying an update.
- **reason** (string) - Optional - Set to "update" when applying an update.

### Response
#### Success Response
- No specific response fields documented.

```

--------------------------------

### Install.Locations.List

Source: https://itch.io/docs/butler/launcher-integration.html

Lists all install locations.

```APIDOC
## Install.Locations.List

### Description
Lists all install locations.

### Method
RPC

### Response
- **locations** (array) - List of install locations.
```

--------------------------------

### Install.PlanUpload

Source: https://itch.io/docs/butler/launcher-integration.html

Plans an upload installation. Called after Install.Queue and before Install.Perform.

```APIDOC
## Install.PlanUpload

### Description
Plans an upload installation. Called after Install.Queue and before Install.Perform.

### Method
CALL

### Endpoint
Install.PlanUpload

### Parameters
No parameters documented.

### Response
#### Success Response
- No specific response fields documented.

```

--------------------------------

### push-preview output example

Source: https://itch.io/docs/butler/pushing.html

Example output from `butler push-preview` showing classification of files as NEW, MODIFIED, DELETED, or SAME, followed by a summary line with counts.

```text
NEW       drwxr-xr-x          - my-game/levels/extra/
MODIFIED  -rw-r--r--   12.30 KiB my-game/data/save.json
DELETED   -rw-r--r--    1.00 KiB my-game/data/old.txt
SAME      -rw-r--r--    8.50 KiB my-game/readme.md
✓ Comparison vs build 12345: 1 new, 1 modified, 1 deleted, 1 unchanged

```

--------------------------------

### Example request with target parameter

Source: https://itch.io/docs/butler/pushing.html

Example URL for the wharf/latest endpoint using the `target` parameter (user/game) and `channel_name`. This is an alternative to using `game_id`.

```http
https://api.itch.io/wharf/latest?target=user/game&channel_name=win32-beta

```

--------------------------------

### Install.Perform

Source: https://itch.io/docs/butler/launcher-integration.html

Long-running call that downloads and installs. Streams notifications such as Progress, TaskStarted, and TaskSucceeded.

```APIDOC
## Install.Perform

### Description
Long-running call that downloads and installs. Streams notifications such as Progress, TaskStarted, and TaskSucceeded.

### Method
RPC

### Parameters
- **taskId** (string) - Required - The task ID from the queue step.

### Notifications
- **Progress** - Periodic updates with `progress`, `eta`, `bps`.
- **TaskStarted** - Fired at start of each sub-task (download, install, update, heal). Includes total size.
- **TaskSucceeded** - Fired when each sub-task finishes successfully.
```

--------------------------------

### Launch (daemon method)

Source: https://itch.io/docs/butler/launcher-integration.html

Launches an installed game, blocking for the full lifetime of the game. Handles prerequisite installation and streams progress events. May send interactive requests during the call.

```APIDOC
## Launch (daemon method)

### Description
Launches an installed game, blocking for the full lifetime of the game. Handles prerequisite installation and streams progress events. May send interactive requests during the call.

### Method
JSON-RPC call

### Parameters
- **caveId** (string) - Required - The ID of the cave to launch.
- **prereqsDir** (string) - Required - A writable directory butler can use to download prerequisite installers into.
- **sandboxing flags** (object) - Optional - Sandboxing options, see SandboxOptions.

### Events Streamed
- **PrereqsStarted** - The list of prereqs about to be installed.
- **PrereqsTaskState** - Per-prereq progress (pending, downloading, ready, installing, done).
- **LaunchRunning** - The game's actual process is up.
- **LaunchExited** - The game has quit.

### Interactive Requests
- **PickManifestAction** - The upload's manifest declared multiple actions; ask the user which to run.
- **AcceptLicense** - Show a EULA, return whether the user accepted.
- **ShellLaunch** - butlerd is handing off a file or folder for your launcher to open via the OS shell.
- **HTMLLaunch** - The upload is an HTML5 game; butlerd needs your launcher to serve it locally and open a window.

Each arrives as a JSON-RPC request from the server during the Launch call. Your client responds with the appropriate result object.

### Sandboxing
Sandboxing is opt-in and currently only meaningful on Linux. See the spec for SandboxOptions.
```

--------------------------------

### Install.Locations.GetByID

Source: https://itch.io/docs/butler/launcher-integration.html

Gets an install location by its ID.

```APIDOC
## Install.Locations.GetByID

### Description
Gets an install location by its ID.

### Method
RPC

### Parameters
- **id** (string) - Required - The ID of the install location.

### Response
- **location** (object) - The install location details.
```

--------------------------------

### Example folder structure with symlink

Source: https://itch.io/docs/butler/pushing.html

Shows a directory layout where game-linux contains a symlink 'data' pointing to ../game-data.

```text
- game-linux
  - game-binary.x64
  - data -> ../game-data
- game-data
  - level1.data

```

--------------------------------

### Fetch.Caves (daemon method)

Source: https://itch.io/docs/butler/launcher-integration.html

Lists a game's installs (caves). Each cave carries its id, the game, and the upload it was installed from. Used to decide what to launch.

```APIDOC
## Fetch.Caves (daemon method)

### Description
Lists a game's installs (caves). Each cave carries its id, the game, and the upload it was installed from. Used to decide what to launch.

### Method
JSON-RPC call

### Parameters
- **gameId** (string) - Required - The game ID to filter caves by.

### Response
- **caves** (array) - List of cave objects, each with:
  - **id** (string) - The cave ID.
  - **game** (object) - The game information.
  - **upload** (object) - The upload it was installed from.
```

--------------------------------

### Install.Locations.Scan

Source: https://itch.io/docs/butler/launcher-integration.html

Walks an install location and rebuilds caves from receipts if the database is lost.

```APIDOC
## Install.Locations.Scan

### Description
Walks an install location and rebuilds caves from receipts if the database is lost.

### Method
RPC

### Parameters
- **id** (string) - Required - The ID of the install location to scan.
```

--------------------------------

### Install.Locations.Add

Source: https://itch.io/docs/butler/launcher-integration.html

Adds a new install location and returns its ID.

```APIDOC
## Install.Locations.Add

### Description
Adds a new install location and returns its ID.

### Method
RPC

### Parameters
- **path** (string) - Required - The directory path for the install location.

### Response
- **id** (string) - The ID of the new install location.
```

--------------------------------

### Dry-run output for steam-sync

Source: https://itch.io/docs/butler/steam-sync.html

Example output showing the plan: channels, depots, sizes, and skipped items. Each channel is pushed with --userversion 987654.

```text
Half-Life 3 (app 123456), branch public, build 987654

  user/game:linux  (1.2 GB on disk, 1.2 GB to download)
    depot 123457    Linux Content                     1.1 GB  manifest 8823...
    depot 123459    Shared Content                    100 MB  manifest 1029...  [all platforms]

  user/game:windows  (1.3 GB on disk, 1.3 GB to download)
    depot 123458    Windows Content                   1.2 GB  manifest 5561...
    depot 123459    Shared Content                    100 MB  manifest 1029...  [all platforms]

  skipped:
    depot 123460    Soundtrack DLC                    DLC for app 123470
    depot 123461    French                            french language pack

Each channel is pushed with --userversion 987654.

```

--------------------------------

### Install.Perform

Source: https://itch.io/docs/butler/launcher-integration.html

Performs the installation or update after queuing. For updates, pass the existing caveId and reason "update". butlerd will use wharf patching when both ends have build metadata.

```APIDOC
## Install.Perform

### Description
Performs the installation or update after queuing. For updates, pass the existing caveId and reason "update". butlerd will use wharf patching when both ends have build metadata.

### Method
CALL

### Endpoint
Install.Perform

### Parameters
#### Request Body
- **caveId** (string) - Optional - The cave ID of the existing installation when applying an update.
- **reason** (string) - Optional - Set to "update" when applying an update.

### Response
#### Success Response
- No specific response fields documented.

```

--------------------------------

### Example request with game_id parameter

Source: https://itch.io/docs/butler/pushing.html

Example URL for the wharf/latest endpoint using the `game_id` parameter and `channel_name`. The `game_id` can be found on the Edit game page's address.

```http
https://api.itch.io/wharf/latest?game_id=123&channel_name=osx-final

```

--------------------------------

### Install.Cancel

Source: https://itch.io/docs/butler/launcher-integration.html

Aborts a running install cleanly using the task ID.

```APIDOC
## Install.Cancel

### Description
Aborts a running install cleanly using the task ID.

### Method
RPC

### Parameters
- **taskId** (string) - Required - The task ID of the install to cancel.
```

--------------------------------

### Verify butler installation on Windows

Source: https://itch.io/docs/butler/installing.html

Run this command in a new Command Prompt after adding butler to your PATH. It should print the version and build information.

```bash
butler version

```

--------------------------------

### Notifications

Source: https://itch.io/docs/butler/launcher-integration.html

Subscribe to progress and task notifications during install and launch operations.

```APIDOC
## Notifications

### Description
Subscribe to progress and task notifications during install and launch operations.

### Method
SUBSCRIBE

### Endpoint
Progress / TaskStarted / TaskSucceeded / PrereqsStarted / PrereqsTaskState / LaunchRunning / LaunchExited

### Parameters
No parameters documented.

### Response
#### Success Response
- No specific response fields documented.

```

--------------------------------

### Fetch.Commons

Source: https://itch.io/docs/butler/launcher-integration.html

Returns flat ID-only summaries of every key, every cave, and every install location. Cheap; use for bulk ownership/install lookups.

```APIDOC
## Fetch.Commons

### Description
Returns flat ID-only summaries of every key, every cave, and every install location. Cheap; use for bulk ownership/install lookups.

### Method
RPC

### Endpoint
Fetch.Commons

### Parameters
#### Request Body
- **fresh** (boolean) - Optional - If true, forces a network round trip. Defaults to false.

### Response
#### Success Response
- **keys** (array) - ID-only summaries of keys.
- **caves** (array) - ID-only summaries of caves.
- **installLocations** (array) - ID-only summaries of install locations.
- **stale** (boolean) - Indicates if the data is stale.

```

--------------------------------

### Start butlerd in the background

Source: https://itch.io/docs/butler/launcher-integration.html

Starts butlerd with JSON output, TCP transport, keep-alive, a local database, the itch.io address, and a custom user agent. Output is redirected to butlerd.log. The shell prints the background job's PID, which is needed later to kill the daemon.

```bash
butler daemon --json --transport tcp --keep-alive \
    --dbpath ./butler-demo.db --address https://itch.io \
    --user-agent "butlerd-demo/0.1" > butlerd.log &

```

--------------------------------

### Dry-run output without --ignore

Source: https://itch.io/docs/butler/pushing.html

Example output from butler push --dry-run without any ignore patterns, showing a list of files and a summary of what would be pushed.

```text
(snip)
-rw-rw-rw- 895.69 KiB ucrtbase.dll
-rw-rw-rw-  74.41 KiB ui_resources_200_percent.pak
-rw-rw-rw-  81.82 KiB vcruntime140.dll
-rw-rw-rw-        6 B version
-rw-rw-rw-  56.10 KiB views_resources_200_percent.pak
√ Would push 103.58 MiB (118 files, 2 dirs, 0 symlinks)

```

--------------------------------

### Spawn butlerd daemon with required flags

Source: https://itch.io/docs/butler/launcher-integration.html

Starts butlerd as a subprocess. --json is required; without it the daemon prints an error and exits. --transport tcp listens on a random local port, --keep-alive allows multiple connections, --dbpath sets the SQLite file, --address is the itch.io site, --user-agent is sent on HTTP requests, and --destiny-pid ties the daemon's lifetime to the launcher's PID.

```bash
butler daemon --json --transport tcp --keep-alive \
    --dbpath /path/to/your-launcher/butler.db \
    --address https://itch.io \
    --user-agent "your-launcher/1.2.3" \
    --destiny-pid <your-launcher-pid>

```

--------------------------------

### Dry-run output with --ignore '*.dll'

Source: https://itch.io/docs/butler/pushing.html

Example output from butler push --dry-run with the --ignore '*.dll' flag, showing that DLL files are excluded and the summary reflects the reduced file count.

```text
(snip)
-rw-rw-rw- 586.13 KiB resources/app.asar
-rw-rw-rw- 233.71 KiB resources/electron.asar
-rw-rw-rw-   1.12 MiB snapshot_blob.bin
-rw-rw-rw-  74.41 KiB ui_resources_200_percent.pak
-rw-rw-rw-        6 B version
-rw-rw-rw-  56.10 KiB views_resources_200_percent.pak
√ Would push 80.05 MiB (70 files, 2 dirs, 0 symlinks)

```

--------------------------------

### Launch a game without a daemon using `butler launch`

Source: https://itch.io/docs/butler/launcher-integration.html

Use this command to launch an installed game for the life of the command without managing a daemon. It runs the same launch machinery in-process against an existing `butler.db`, answers interactive requests non-interactively, and stays alive until the game exits. Requires `--dbpath` and either `--game` or `--cave`.

```bash
butler --json --dbpath /path/to/butler.db launch --game 123456 \
  --prereqs-dir /path/to/prereqs

```

--------------------------------

### Fetch.Caves

Source: https://itch.io/docs/butler/launcher-integration.html

Fetches the list of caves (installed games) to badge installed games.

```APIDOC
## Fetch.Caves

### Description
Fetches the list of caves (installed games) to badge installed games.

### Method
CALL

### Endpoint
Fetch.Caves

### Parameters
No parameters documented.

### Response
#### Success Response
- No specific response fields documented.

```

--------------------------------

### HTMLLaunch

Source: https://itch.io/docs/butler/launcher-integration.html

Handle an HTML launch prompt during launch.

```APIDOC
## HTMLLaunch

### Description
Handle an HTML launch prompt during launch.

### Method
CALL

### Endpoint
HTMLLaunch

### Parameters
No parameters documented.

### Response
#### Success Response
- No specific response fields documented.

```

--------------------------------

### CheckUpdate

Source: https://itch.io/docs/butler/launcher-integration.html

Checks for updates for installed games. Pass an array of cave IDs to scope to specific games, or omit to check all installed games. Returns an array of GameUpdate records.

```APIDOC
## CheckUpdate

### Description
Checks for updates for installed games. Pass an array of cave IDs to scope to specific games, or omit to check all installed games. Returns an array of GameUpdate records.

### Method
CALL

### Endpoint
CheckUpdate

### Parameters
#### Request Body
- **caveIds** (array of string) - Optional - Array of cave IDs to scope the update check. Omit to check all installed games.

### Response
#### Success Response
- **gameUpdates** (array of GameUpdate) - Array of GameUpdate records, each carrying the cave ID, the new upload(s) to choose from, and whether the update is "direct" (i.e., on the same channel the cave was originally installed from).

```

--------------------------------

### Install.Locations.Remove

Source: https://itch.io/docs/butler/launcher-integration.html

Removes an install location.

```APIDOC
## Install.Locations.Remove

### Description
Removes an install location.

### Method
RPC

### Parameters
- **id** (string) - Required - The ID of the install location to remove.
```

--------------------------------

### ShellLaunch

Source: https://itch.io/docs/butler/launcher-integration.html

Handle a shell launch prompt during launch.

```APIDOC
## ShellLaunch

### Description
Handle a shell launch prompt during launch.

### Method
CALL

### Endpoint
ShellLaunch

### Parameters
No parameters documented.

### Response
#### Success Response
- No specific response fields documented.

```

--------------------------------

### GET https://api.itch.io/wharf/latest - Query latest version

Source: https://itch.io/docs/butler/pushing.html

HTTP GET request to the itch.io API to query the latest user-version for a given channel. No authentication required. Returns a JSON object with a `latest` field if the latest build has a user-version.

```http
GET https://api.itch.io/wharf/latest

```

--------------------------------

### AcceptLicense

Source: https://itch.io/docs/butler/launcher-integration.html

Accept a license prompt during launch.

```APIDOC
## AcceptLicense

### Description
Accept a license prompt during launch.

### Method
CALL

### Endpoint
AcceptLicense

### Parameters
No parameters documented.

### Response
#### Success Response
- No specific response fields documented.

```

--------------------------------

### Apply a patch to a new directory with butler apply

Source: https://itch.io/docs/butler/offline.html

Applies the patch to a fresh directory (`new-build/`) instead of patching in place, leaving the old build untouched. `--staging-dir` is required and `--signature` verifies the result.

```bash
butler apply --staging-dir tmp/ --dir new-build/ --signature patch.pwr.sig patch.pwr old-build/

```

--------------------------------

### Run steam-sync using a config file

Source: https://itch.io/docs/butler/steam-sync.html

Runs the sync using settings from a TOML config file. This is an alternative to passing all options on the command line.

```bash
butler steam-sync --from-config sync.toml

```

--------------------------------

### Fetch.Caves

Source: https://itch.io/docs/butler/launcher-integration.html

Returns the user's installed games (caves). Can be filtered by gameId.

```APIDOC
## Fetch.Caves

### Description
Returns the user's installed games (caves). Can be filtered by gameId.

### Method
RPC

### Endpoint
Fetch.Caves

### Parameters
#### Request Body
- **gameId** (string) - Optional - Filter caves by game ID.
- **fresh** (boolean) - Optional - If true, forces a network round trip. Defaults to false.

### Response
#### Success Response
- **caves** (array) - List of caves.
- **stale** (boolean) - Indicates if the data is stale.

```

--------------------------------

### butler push command syntax

Source: https://itch.io/docs/butler/pushing.html

The core command to upload a build. `directory` is the folder or .zip to upload, `user/game` is the lowercase project identifier (e.g., `finji/overland`), and `channel` is the slot name (e.g., `windows-beta`). Channel names determine initial tags but can be changed later.

```bash
butler push directory user/game:channel

```

--------------------------------

### Kill the daemon

Source: https://itch.io/docs/butler/launcher-integration.html

Terminates butlerd using the PID printed when it was started in the background.

```bash
kill 23847

```

--------------------------------

### Listen notification JSON

Source: https://itch.io/docs/butler/launcher-integration.html

Example of the listen notification JSON that appears in the log, containing the secret and the TCP address.

```json
{"type":"butlerd/listen-notification","secret":"abc-def-…","tcp":{"address":"127.0.0.1:54321"}}

```

--------------------------------

### Run a steam-sync job with a cache directory

Source: https://itch.io/docs/butler/steam-sync.html

Syncs a Steam app to an itch.io game using the provided cache directory. Use this in CI after setting the required credentials via flags or environment variables.

```bash
butler steam-sync 123456 user/game --cache-dir "$CACHE_DIR"

```

--------------------------------

### PickManifestAction

Source: https://itch.io/docs/butler/launcher-integration.html

Answer a manifest action prompt during launch.

```APIDOC
## PickManifestAction

### Description
Answer a manifest action prompt during launch.

### Method
CALL

### Endpoint
PickManifestAction

### Parameters
No parameters documented.

### Response
#### Success Response
- No specific response fields documented.

```

--------------------------------

### GET https://api.itch.io/wharf/latest

Source: https://itch.io/docs/butler/pushing.html

Queries the latest user-version for a given channel. Does not require authentication. Returns a JSON object with the latest user-version, or an error if the game is private.

```APIDOC
## GET https://api.itch.io/wharf/latest

### Description
Queries the latest user-version for a given channel. Does not require authentication.

### Method
GET

### Endpoint
https://api.itch.io/wharf/latest

### Parameters
#### Query Parameters
- **channel_name** (string) - Required - The name of the channel to query.
- **game_id** (numeric) - Optional - Identifier of the game (find it in _Edit game_). Either this or `target` must be provided.
- **target** (string) - Optional - User/game, just like the `butler push` command. Either this or `game_id` must be provided.

### Response
#### Success Response (200)
- **latest** (string) - The latest user-version for the given channel. If the latest build doesn't have a user-version, this field will not be present.

#### Response Example
{
  "latest": "106"
}

### Error Handling
If the game's visibility level is set to `Private`, this endpoint will return the error 'invalid game' to avoid leaking information about unreleased games.

### Example Requests
https://api.itch.io/wharf/latest?target=user/game&channel_name=win32-beta

https://api.itch.io/wharf/latest?game_id=123&channel_name=osx-final
```

--------------------------------

### Apply a patch with butler apply

Source: https://itch.io/docs/butler/offline.html

Uses a patch file to transform an old build into the new one. `--staging-dir` is required and holds temporary files and checkpoints, making the operation resumable. `--signature` verifies patched files against the new build's hashes; the command fails if anything does not match.

```bash
butler apply --staging-dir tmp/ --signature patch.pwr.sig patch.pwr old-build/

```

--------------------------------

### Response JSON for wharf/latest

Source: https://itch.io/docs/butler/pushing.html

Example JSON response from the wharf/latest endpoint. The `latest` field contains the latest user-version string. If the latest build has no user-version, the field is absent.

```json
{
  latest: "106"
}

```

--------------------------------

### butler push-preview

Source: https://itch.io/docs/butler/pushing.html

Compares a directory against the channel's previous build and reports which files would be added, modified, deleted, or left unchanged. Authenticates, downloads the previous build's signature, hashes local files, and prints a per-entry classification.

```APIDOC
## butler push-preview

### Description
Compares a directory against the channel's previous build and reports which files would be added, modified, deleted, or left unchanged. Authenticates, downloads the previous build's signature, hashes local files, and prints a per-entry classification.

### Usage
butler push-preview [options] <directory> <target>

### Parameters
- **directory** (string) - Required - The local directory to compare.
- **target** (string) - Required - The channel target in the form `user/game:channel`.

### Options
- **--changes-only** - Hide unchanged entries from the listing on big builds. The summary line still reflects the full counts.
- **--dereference** - Walk-related flag from `butler push`.
- **--fix-permissions** - Walk-related flag from `butler push`.
- **--auto-wrap** - Walk-related flag from `butler push`.
- **--auto-unzip** - Walk-related flag from `butler push`.
- **--ignore** - Walk-related flag from `butler push`.

### Output
Prints a per-entry classification with lines like:
NEW       drwxr-xr-x          - my-game/levels/extra/
MODIFIED  -rw-r--r--   12.30 KiB my-game/data/save.json
DELETED   -rw-r--r--    1.00 KiB my-game/data/old.txt
SAME      -rw-r--r--    8.50 KiB my-game/readme.md

And a summary line:
✓ Comparison vs build 12345: 1 new, 1 modified, 1 deleted, 1 unchanged

If the channel doesn't have a previous build yet, every entry is reported as `NEW`.

### Notes
- Hashing the source costs roughly the same as the diff pass of a real push.
- Build creation flags (`--userversion`, `--hidden`, `--if-changed`) are not applicable since `push-preview` never creates a build.
```

--------------------------------

### butler push-preview command

Source: https://itch.io/docs/butler/pushing.html

Command to preview changes between a local directory and the channel's previous build. It authenticates, downloads the previous build's signature, hashes local files, and prints a per-entry classification.

```bash
butler push-preview my-game user/mygame:win-64

```

--------------------------------

### Sync a branch with --branch and --password

Source: https://itch.io/docs/butler/steam-sync.html

Syncs a non-public branch. --password is only needed for password-protected branches. The example shows syncing a beta branch and a playtest branch with a password.

```bash
butler steam-sync 123456 user/game --branch beta
butler steam-sync 123456 user/game --branch playtest --password hunter2

```

--------------------------------

### Fetch.ProfileOwnedKeys

Source: https://itch.io/docs/butler/launcher-integration.html

Returns every download key the user owns, each key carrying the associated game.

```APIDOC
## Fetch.ProfileOwnedKeys

### Description
Returns every download key the user owns, each key carrying the associated game.

### Method
RPC

### Endpoint
Fetch.ProfileOwnedKeys

### Parameters
#### Request Body
- **fresh** (boolean) - Optional - If true, forces a network round trip. Defaults to false.

### Response
#### Success Response
- **keys** (array) - List of download keys.
  - **game** (object) - The associated game.
- **stale** (boolean) - Indicates if the data is stale (not refreshed recently).

```

--------------------------------

### Authorize endpoint URL for OAuth flow

Source: https://itch.io/docs/butler/launcher-integration.html

Open the user's browser to this URL to start the OAuth flow. Replace placeholders with your client ID, redirect URI, state, and code challenge.

```text
https://itch.io/user/oauth?
  client_id=<your-client-id>
  &scope=itch
  &redirect_uri=<your-redirect-uri>
  &response_type=code
  &state=<random-state>
  &code_challenge=<code-challenge>
  &code_challenge_method=S256

```
Tokens:
Raw