### Typical Launcher Lifecycle - Install Game

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Handles the process of installing a game, from fetching available uploads to performing the installation and subscribing to progress notifications.

```Go
# Fetch.GameUploads (compatible:true)
# Install.Queue -> Install.PlanUpload -> user confirms -> Install.Perform
# (subscribe to Progress / TaskStarted / TaskSucceeded notifications)
```

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

### Install specific prerequisites with butler

Source: https://github.com/itchio/butler/blob/master/docs/prerequisites.md

To install specific prerequisites, provide their names as arguments. Use the `--elevate` flag if administrative rights are required for installation. Without `--elevate`, the installation will likely fail with a permission error.

```bash
butler test-prereqs --elevate <prereq1> <prereq2>
```

```bash
butler test-prereqs <prereq1> <prereq2>
```

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

### Install.Queue

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Queues an install operation to be later performed via Install.Perform. This method allows for detailed configuration of the installation process, including specifying game details, install locations, and download behavior.

```APIDOC
## Install.Queue (client request)

### Description
Queues an install operation to be later performed via Install.Perform.

### Parameters
#### Request Body
- **caveId** (string) - Optional - ID of the cave to perform the install for. If not specified, will create a new cave.
- **reason** (DownloadReason) - Optional - If unspecified, will default to ‘install’.
- **installLocationId** (string) - Optional - If CaveID is not specified, ID of an install location to install to.
- **noCave** (boolean) - Optional - If set, InstallFolder can be set and no cave record will be read or modified.
- **installFolder** (string) - Optional - When NoCave is set, exactly where to install.
- **game** (Game) - Optional - Which game to install. If unspecified and caveId is specified, the same game will be used.
- **upload** (Upload) - Optional - Which upload to install. If unspecified and caveId is specified, the same upload will be used.
- **build** (Build) - Optional - Which build to install. If unspecified and caveId is specified, the same build will be used.
- **ignoreInstallers** (boolean) - Optional - If true, do not run windows installers, just extract whatever to the install folder.
- **stagingFolder** (string) - Optional - A folder that butler can use to store temporary files, like partial downloads, checkpoint files, etc.
- **queueDownload** (boolean) - Optional - If set, and the install operation is successfully disambiguated, will queue it as a download for butler to drive. See Downloads.Drive.
- **fastQueue** (boolean) - Optional - Don’t run install prepare (assume we can just run it at perform time)

### Result
#### Success Response (200)
- **id** (string)
- **reason** (DownloadReason)
- **caveId** (string)
- **game** (Game)
- **upload** (Upload)
- **build** (Build)
- **installFolder** (string)
- **stagingFolder** (string)
```

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

### Install.Perform

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Performs an installation that was previously queued. This operation continues the installation process and can be cancelled using the Install.Cancel method.

```APIDOC
## Install.Perform

### Description
Performs an installation that was previously queued. This operation continues the installation process and can be cancelled using the Install.Cancel method.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **id** (string) - Required - ID that can be later used in Install.Cancel
- **stagingFolder** (string) - Required - The folder turned by Install.Queue

### Request Example
```json
{
  "id": "string",
  "stagingFolder": "string"
}
```

### Response
#### Success Response (200)
- **caveId** (string) - Description
- **events** (InstallEvent[]) - Description

#### Response Example
```json
{
  "caveId": "string",
  "events": [
    // InstallEvent objects
  ]
}
```
```

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

### JSON progress output example

Source: https://github.com/itchio/butler/blob/master/docs/offline.md

Example of a progress update in JSON output mode.

```json
{"type": "progress", "percentage": "80"}
```

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

### Example API Request with Target

Source: https://github.com/itchio/butler/blob/master/docs/pushing.md

An example of how to query the latest game version using the 'target' parameter.

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

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

### Install Game Methods

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Methods for managing game installations, including queuing, planning, performing, and cancelling installs. This process involves multiple steps and provides progress notifications.

```APIDOC
## Install Methods

Installs are a three-step process: queue, plan, and perform.

### `Install.Queue`

Queues a game for installation. Requires `game`, `upload` (and optionally `build`), `installLocationId`, and `reason`. Returns the staging folder. Set `queueDownload: true` to have Butler manage the download.

### `Install.PlanUpload`

(Optional but recommended) Computes disk space requirements and detects installer type for a queued task. Use the result to confirm space requirements with the user.

### `Install.Perform`

Initiates the download and installation process for a queued task. Butler streams notifications like `Progress`, `TaskStarted`, and `TaskSucceeded` on the same connection.

### `Install.Cancel`

Aborts an ongoing installation task using its task ID.
```

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

### Install.Queue (client request)

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Queues an install operation to be later performed via Install.Perform.

```APIDOC
## Install.Queue (client request)

### Description
Queues an install operation to be later performed via Install.Perform.

### Parameters
#### Request Body
- **caveId** (string) - Required - The ID of the cave to install.
- **reason** (DownloadReason) - Required - The reason for the download.
- **installLocationId** (string) - Required - The ID of the install location.
- **noCave** (boolean) - Optional - If true, do not create a cave.
- **installFolder** (string) - Optional - The folder to install the game to.
- **game** (Game) - Optional - Game details.
- **upload** (Upload) - Optional - Upload details.
- **build** (Build) - Optional - Build details.
- **ignoreInstallers** (boolean) - Optional - If true, ignore installers.
- **stagingFolder** (string) - Optional - The staging folder for the installation.
- **queueDownload** (boolean) - Optional - If true, queue the download.
- **fastQueue** (boolean) - Optional - If true, use fast queueing.

### Response
#### Success Response (200)
- **id** (string) - The ID of the queued install operation.
- **reason** (DownloadReason) - The reason for the download.
- **caveId** (string) - The ID of the cave.
- **game** (Game) - Game details.
- **upload** (Upload) - Upload details.
- **build** (Build) - Build details.
- **installFolder** (string) - The folder where the game is installed.
- **stagingFolder** (string) - The staging folder for the installation.
- **installLocationId** (string) - The ID of the install location.
```

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

### Typical Launcher Lifecycle - Startup

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Handles the initial setup of the Butler daemon, authentication, and profile loading on launcher startup.

```Go
# ensure butler binary present
# spawn butler daemon, parse listen-notification
# open TCP, send Meta.Authenticate
client.Profile.List()
  # -> if a remembered profile: Profile.UseSavedLogin (timeout: ~5s)
  # -> else: run OAuth+PKCE flow, then Profile.LoginWithOAuthCode
```

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

### Install.Locations.List

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Lists all available install locations managed by Butler. This request takes no parameters and returns a summary of each install location.

```APIDOC
## Install.Locations.List

### Description
Lists all available install locations managed by Butler.

### Method
(Not specified, assumed client request)

### Endpoint
(Not specified)

### Parameters
*None*

### Result
#### Success Response
- **installLocations** (InstallLocationSummary[]) - A list of install location summaries.
```

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

### Install.PlanUpload

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Returns installer type and disk usage info for a specific upload. This is the slow part of install planning (network I/O + file inspection).

```APIDOC
## Install.PlanUpload

### Description
Returns installer type and disk usage info for a specific upload. This is the slow part of install planning (network I/O + file inspection).

### Parameters
#### Path Parameters
* None
#### Query Parameters
* None
#### Request Body
* `id` (string) - Optional - ID for cancellation support. If provided, can be cancelled via Install.Cancel
* `uploadId` (number) - Required - 
* `downloadSessionId` (string) - Optional - 

### Request Example
```json
{
  "id": "string",
  "uploadId": 0,
  "downloadSessionId": "string"
}
```

### Response
#### Success Response (200)
* `info` (InstallPlanInfo) - 

#### Response Example
```json
{
  "info": {}
}
```
```

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

### Install.VersionSwitch.Queue

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Prepares to queue a version switch for a specific game installation. The client will receive a prompt to pick the desired version.

```APIDOC
## Install.VersionSwitch.Queue

### Description
Prepares to queue a version switch for a game installation. The client will receive an `InstallVersionSwitchPick` prompt.

### Method
(Not specified, assumed to be a client request)

### Endpoint
(Not specified)

### Parameters
#### Path Parameters
(None specified)

#### Query Parameters
(None specified)

#### Request Body
- **caveId** (string) - Required - The identifier of the cave (game installation) for which to queue a version switch.

### Request Example
(Not specified)

### Response
#### Success Response (200)
(None specified)

#### Response Example
(None specified)
```

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

### AllowSandboxSetup

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Asks the user to allow sandbox setup. This may be followed by a UAC prompt (on Windows) or a pkexec dialog (on Linux) if the user allows. This is sent during a Launch event.

```APIDOC
## AllowSandboxSetup

### Description
Asks the user to allow sandbox setup. Will be followed by a UAC prompt (on Windows) or a pkexec dialog (on Linux) if the user allows. Sent during a Launch event.

### Parameters
none

### Result
#### Success Response
- **allow** (boolean) - Set to true if user allowed the sandbox setup, false otherwise
```

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

### Typical Launcher Lifecycle - Main Window

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Fetches profile-owned keys and installed game badges for the main window. Periodically checks for updates in the background.

```Go
# Fetch.ProfileOwnedKeys (fresh:false; refetch with fresh:true)
# Fetch.Caves to badge installed games
# CheckUpdate in the background
```

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

### Launch (client request)

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Attempt to launch an installed game. This is a client request that initiates the game launch process.

```APIDOC
## Launch (client request)

### Description
Attempt to launch an installed game.

### Method
(Not specified, assumed to be a client-side SDK call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **caveId** (string) - Required - The ID of the cave to launch
- **prereqsDir** (string) - Required - The directory to use to store installer files for prerequisites
- **forcePrereqs** (boolean) - Optional - Force installing all prerequisites, even if they’re already marked as installed
- **sandbox** (boolean) - Optional - Enable sandbox (regardless of manifest opt-in)
- **sandboxOptions** (SandboxOptions) - Optional - Sandbox configuration options. Only applied when sandbox is enabled.
- **extraArgs** (string[]) - Optional - Additional command-line arguments appended after manifest action args.

### Request Example
```json
{
  "caveId": "your_cave_id",
  "prereqsDir": "/path/to/prereqs",
  "forcePrereqs": false,
  "sandbox": true,
  "sandboxOptions": {},
  "extraArgs": ["--arg1", "--arg2"]
}
```

### Response
#### Success Response (200)
- none

#### Response Example
None
```

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

### JSON log output example

Source: https://github.com/itchio/butler/blob/master/docs/offline.md

Example of a log message in JSON output mode.

```json
{"type": "log", "message": "Doing something", "level": "info"}
```

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

### Start butlerd Daemon

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/layout.md

Starts an instance of the butler daemon with JSON output and a specified database path. Use the --log option to log all TCP message exchanges.

```bash
butler daemon --json --dbpath path/to/butler.db
```

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

### Dry Run Example with Ignore '*.dll'

Source: https://github.com/itchio/butler/blob/master/docs/pushing.md

This example demonstrates the --dry-run flag's output when the '--ignore '*.dll'' pattern is applied, showing a reduced list of files and a smaller total size.

```bash
(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)
```

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

### Install.Plan

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Calculates space requirements for game installations. This method is deprecated and users should prefer Install.GetUploads and Install.PlanUpload for better performance and cancellation support.

```APIDOC
## Install.Plan (client request)

### Description
Calculates space requirements for game installations. This method is deprecated and users should prefer Install.GetUploads and Install.PlanUpload for better performance and cancellation support.

### Parameters
#### Path Parameters
- `gameId` (number) - Required - The ID of the game.
- `downloadSessionId` (string) - Optional - The ID of the download session.
- `uploadId` (number) - Optional - The ID of the upload.

### Result
#### Success Response (200)
- `game` (Game) - Information about the game.
- `uploads` (Upload[]) - A list of available uploads.
- `info` (InstallPlanInfo) - Additional information about the installation plan.
```

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

### LaunchRunning (notification)

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Sent during Launch, when the game is configured, prerequisites are installed, sandbox is set up (if enabled), and the game is actually running.

```APIDOC
## LaunchRunning (notification)

### Description
Sent during Launch, when the game is configured, prerequisites are installed, sandbox is set up (if enabled), and the game is actually running.

### Payload
None

### Response Example
None
```

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

### Initialize Docsify with Configuration

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/index.html

Configure the docsify instance with options for name, theme color, search, markdown parsing, and plugins. This setup is essential for the documentation site's behavior and appearance.

```javascript
window.$docsify = {
  name: "butlerd",
  themeColor: "#fa5c5c",
  repo: "",
  search: {
    paths: ["/"],
    namespace: "butlerd",
    depth: 3,
  },
  markdown: {
    gfm: true,
    tables: true,
  },
  noEmoji: true,
  plugins: [
    function (hook, vm) {
      hook.doneEach(function () {
        tippy("[data-tip-selector]", {
          placement: "right",
          allowHTML: true,
          arrow: true,
          content: (el) => {
            let sel = el.dataset.tipSelector;
            let tipContent = document.querySelector(sel);
            if (tipContent) {
              return tipContent.cloneNode(true);
            }
            return null;
          },
          interactive: true,
          trigger: "click",
          maxWidth: "400px",
        });
      });
    },
  ],
};
localStorage.clear();
```

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

### Butler Install Without Cave

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Install directly into a specified folder without creating a database record. Useful for one-shot extracts or portable bundles.

```Go
butler.Install.Queue(InstallParams{
  noCave: true,
  installFolder: "/path/to/install",
})
```

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

### Install.CreateShortcut

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Creates a shortcut for an existing cave. This is useful for providing quick access to installed games or applications.

```APIDOC
## Install.CreateShortcut

### Description
Creates a shortcut for an existing cave. This is useful for providing quick access to installed games or applications.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **caveId** (string) - Required - The ID of the cave for which to create a shortcut.

### Request Example
```json
{
  "caveId": "string"
}
```

### Response
#### Success Response (200)
- None

#### Response Example
None
```

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

### Install.Locations.Scan

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Scans for install locations, optionally using a legacy market path.

```APIDOC
## Install.Locations.Scan

### Description
Initiates a scan for install locations. It can optionally take a path to a legacy market database.

### Method
(Not specified, assumed to be a client request)

### Endpoint
(Not specified)

### Parameters
#### Path Parameters
(None specified)

#### Query Parameters
(None specified)

#### Request Body
(None specified)

### Parameters
#### Path Parameters
- **legacyMarketPath** (string) - Optional - path to a legacy marketDB

### Request Example
(Not specified)

### Response
#### Success Response (200)
- **numFoundItems** (number) - Description not specified
- **numImportedItems** (number) - Description not specified

#### Response Example
(Not specified)
```

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

### List available prerequisites with butler

Source: https://github.com/itchio/butler/blob/master/docs/prerequisites.md

Run `butler test-prereqs` without arguments to see a list of all prerequisites that can be installed.

```bash
butler test-prereqs
```

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

### JSON-RPC 2.0 Result Response Example

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/layout.md

An example of a JSON-RPC 2.0 successful result response, containing the version information.

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "version": "v17.0.0",
    "versionString": "v17.0.0, built in the future"
  }
}
```

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

### Install.Locations.GetByID

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Retrieves details of a specific install location by its identifier.

```APIDOC
## Install.Locations.GetByID

### Description
Retrieves the details of an install location using its unique identifier.

### Method
(Not specified, assumed to be a client request)

### Endpoint
(Not specified)

### Parameters
#### Path Parameters
(None specified)

#### Query Parameters
(None specified)

#### Request Body
(None specified)

### Parameters
#### Path Parameters
- **id** (string) - Required - identifier of the install location to remove

### Request Example
(Not specified)

### Response
#### Success Response (200)
- **installLocation** (InstallLocationSummary) - Description not specified

#### Response Example
(Not specified)
```

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

### Start butlerd Daemon in Background

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Starts the butlerd daemon in the background, directing JSON output to a log file. This command is used for setting up a demo environment.

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

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

### Verify butler Installation

Source: https://github.com/itchio/butler/blob/master/docs/installing.md

Run this command in your terminal to check if butler is installed and accessible. It should display the version information.

```bash
butler version
```

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

### Fetch.Commons

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Fetches common data including download keys, caves, and install locations. This operation does not require any parameters.

```APIDOC
## Fetch.Commons

### Description
Fetches common data including download keys, caves, and install locations. This operation does not require any parameters.

### Method
(Not specified, likely a client-side call)

### Endpoint
(Not specified)

### Parameters
* none

### Result
#### Success Response
- **downloadKeys** (DownloadKeySummary[]) - 
- **caves** (CaveSummary[]) - 
- **installLocations** (InstallLocationSummary[]) - 

### Response Example
{
  "downloadKeys": [
    {
      "id": "string",
      "gameId": "number",
      "productId": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "owned": "boolean",
      "downloads": "number"
    }
  ],
  "caves": [
    {
      "id": "string",
      "gameId": "number",
      "productId": "number",
      "name": "string",
      "path": "string",
      "lastImportedAt": "string",
      "lastPushedAt": "string",
      "lastVisitedAt": "string",
      "size": "number",
      "running": "boolean",
      "windows": "boolean",
      "linux": "boolean",
      "osx": "boolean",
      "hasUnreadNotifications": "boolean"
    }
  ],
  "installLocations": [
    {
      "id": "string",
      "path": "string",
      "used": "boolean",
      "total": "number",
      "free": "number"
    }
  ]
}
```

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

### Example API Request with Game ID

Source: https://github.com/itchio/butler/blob/master/docs/pushing.md

An example of how to query the latest game version using the 'game_id' parameter. 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.Locations.Add

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Adds a new install location to Butler. You can optionally provide an ID, otherwise one will be generated. Requires a path for the new location.

```APIDOC
## Install.Locations.Add

### Description
Adds a new install location to Butler. An identifier can be optionally provided; otherwise, it will be generated. A path for the new location is required.

### Method
(Not specified, assumed client request)

### Endpoint
(Not specified)

### Parameters
#### Path Parameters
*None*

#### Query Parameters
*None*

#### Request Body
- **id** (string) - Optional - Identifier of the new install location. If not specified, will be generated.
- **path** (string) - Required - Path of the new install location.

### Result
#### Success Response
- **installLocation** (InstallLocationSummary) - The summary of the newly added install location.
```

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

### PrereqsFailed

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Sent during Launch, when one or more prerequisites have failed to install. The user may choose to proceed with the launch anyway.

```APIDOC
## PrereqsFailed (client caller)

### Description
Sent during Launch, when one or more prerequisites have failed to install. The user may choose to proceed with the launch anyway.

### Parameters
#### Request Body
- **error** (string) - Required - Short error
- **errorStack** (string) - Required - Longer error (to include in logs)

### Result
#### Success Response (200)
- **continue** (boolean) - Set to true if the user wants to proceed with the launch in spite of the prerequisites failure
```

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

### Spawn Butler Daemon

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Start the butler daemon as a subprocess of your launcher. Ensure the --json flag is used as it's required for proper daemon operation. The --destiny-pid flag ties the daemon's lifetime to your launcher's process ID.

```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>
```

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

### Fetch User Library Methods

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Methods for retrieving information about the user's library, including owned games, collections, and installed games. These methods can optionally fetch fresh data from the network by passing `fresh: true`.

```APIDOC
## Fetch Methods

These methods retrieve data from Butler's local cache. To force a network refresh, pass `fresh: true` in the parameters.

### `Fetch.ProfileOwnedKeys`

Retrieves every download key the user owns, including associated game information.

### `Fetch.ProfileCollections`

Retrieves the user's collections.

### `Fetch.CollectionGames`

Retrieves the games within a specific collection.

### `Fetch.ProfileGames`

Retrieves games authored by the user, relevant for creator-facing launchers.

### `Fetch.Game`

Fetches a single game by its ID.

### `Fetch.Caves`

Retrieves records for all installed games (caves) owned by the user. Can be filtered by `gameId`.

### `Fetch.Cave`

Retrieves a specific installed game record (cave) by its ID.

### `Fetch.Commons`

Provides flat, ID-only summaries of all owned keys, installed caves, and install locations. Useful for bulk lookups.

### `Fetch.Search.Games`

Searches for games.
```

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

### JSON-RPC 2.0 Request Example

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/layout.md

An example of a JSON-RPC 2.0 request to get the version information. Over TCP, each JSON object is sent on a single line.

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "Version.Get",
  "params": {}
}
```

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

### Butler Install Location Management

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Manage game installation locations using Butler's API. Use List, Add, Remove, and GetByID to control where games can be installed.

```Go
installLocations := butler.Install.Locations.List()
installLocation := butler.Install.Locations.GetByID(id)
butler.Install.Locations.Add(path)
butler.Install.Locations.Remove(id)
```

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

### Typical Launcher Lifecycle - Play Game

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Manages launching a game, including handling prerequisites, streaming status, and interactive prompts like manifest selection or license acceptance.

```Go
# Launch(caveId, prereqsDir)
# (subscribe to PrereqsStarted / PrereqsTaskState / LaunchRunning / LaunchExited;
#  answer PickManifestAction / AcceptLicense / ShellLaunch / HTMLLaunch as needed)
```

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

### JSON-RPC 2.0 Error Response Example

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/layout.md

An example of a JSON-RPC 2.0 error response, indicating a problem with a specific error code and message.

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 100,
    "message": "Something bad happened"
  }
}
```

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

### Install.GetUploads

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Retrieves a list of available uploads for a game, optionally narrowed by platform and format. This is a fast operation as it does not involve file I/O.

```APIDOC
## Install.GetUploads (client request)

### Description
Retrieves the list of available uploads for a game, narrowed by platform/format. This is the fast part of install planning (no file I/O).

### Parameters
#### Path Parameters
- `gameId` (number) - Required - The ID of the game.

### Result
#### Success Response (200)
- `game` (Game) - Information about the game.
- `uploads` (Upload[]) - A list of available uploads.
```

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

### Start butlerd Daemon with Stdio Transport

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/layout.md

Starts the butler daemon using the stdio transport for JSON-RPC communication over stdin/stdout. Logging is redirected to stderr.

```bash
butler daemon --json --transport stdio --dbpath path/to/butler.db
```

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

### JSON-RPC 2.0 Notification Example

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/layout.md

An example of a JSON-RPC 2.0 notification, used for sending messages like logs without expecting a reply. Notifications do not have an 'id'.

```json
{
  "jsonrpc": "2.0",
  "method": "Log",
  "params": {
    "msg": "Just a log message, it doesn't need a reply so it doesn't have an ID"
  }
}
```

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

### Typical Launcher Lifecycle - Uninstall Game

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Handles the user-initiated uninstallation of a game.

```Go
# Uninstall.Perform(caveId)
```

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

### Publish.PushPreview

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Initiates a client request to push a preview build. It returns details about the preview, including channel information, build status, sizes, and file changes.

```APIDOC
## Publish.PushPreview (client request)

### Description
This operation allows a client to request a preview build push. It provides information necessary to track and manage the preview build process.

### Method
Not specified (client request)

### Endpoint
Not specified

### Parameters
Not specified

### Request Example
Not specified

### Response
#### Success Response (200)
- **channel** (string) - The name of the channel for the preview.
- **hasParent** (boolean) - Indicates if the preview has a parent build.
- **parentBuildId** (number) - The ID of the parent build, if applicable.
- **sourceSize** (number) - The size of the source build.
- **comparison** (PublishPushComparison) - Details about the comparison with the previous build.
- **topChangedFiles** (PublishPushTopChangedFiles) - Information about the top changed files in the preview.

#### Response Example
Not specified
```

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

### Dry Run Example without Ignore

Source: https://github.com/itchio/butler/blob/master/docs/pushing.md

The --dry-run flag previews which files would be pushed without actually uploading them. This example shows the output when no --ignore flags are used.

```bash
(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)
```

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

### Install.Locations.Remove

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Removes a specific install location by its identifier.

```APIDOC
## Install.Locations.Remove

### Description
Removes a specific install location identified by its ID.

### Method
(Not specified, assumed to be a client request)

### Endpoint
(Not specified)

### Parameters
#### Path Parameters
(None specified)

#### Query Parameters
(None specified)

#### Request Body
(None specified)

### Parameters
#### Path Parameters
- **id** (string) - Required - identifier of the install location to remove

### Request Example
(Not specified)

### Response
#### Success Response (200)
- **Result**: none

#### Response Example
(Not specified)
```

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

### Typical Launcher Lifecycle - Update Game

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Handles the user-initiated update process for a game, queuing and performing the update.

```Go
# Install.Queue (reason:"update", caveId:…)
# Install.Perform
```

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

### InstallVersionSwitchPick

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Allows the user to select which version of a game to switch to. It takes the current cave, upload, and available builds as input and returns the index of the chosen version or a negative index to abort.

```APIDOC
## InstallVersionSwitchPick

### Description
Lets the user pick which version to switch to. A negative index aborts the version switch.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `cave` (Cave) - Required - The current cave.
- `upload` (Upload) - Required - The current upload.
- `builds` (Build[]) - Required - An array of available builds.

### Request Example
```json
{
  "cave": { ... },
  "upload": { ... },
  "builds": [
    { ... },
    { ... }
  ]
}
```

### Response
#### Success Response (200)
- `index` (number) - The index of the selected version. A negative value indicates cancellation.

#### Response Example
```json
{
  "index": 1
}
```
```

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

### Request butlerd Version

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Sends a request to butlerd to get its version information using the Version.Get method.

```json
{"jsonrpc":"2.0","id":2,"method":"Version.Get","params":{}}
```

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

### Launch a Game

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Initiates the launch of a game, handling prerequisites and streaming status updates. The call blocks for the game's lifetime.

```Go
client.Launch(caveId, prereqsDir)
// subscribe to PrereqsStarted / PrereqsTaskState / LaunchRunning / LaunchExited;
// answer PickManifestAction / AcceptLicense / ShellLaunch / HTMLLaunch as needed
```

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

### HTMLLaunch

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Asks the client to perform an HTML launch, opening an HTML5 game, ideally in an embedded browser. This is sent during a Launch event.

```APIDOC
## HTMLLaunch

### Description
Asks the client to perform an HTML launch, ie. open an HTML5 game, ideally in an embedded browser. Sent during a Launch event.

### Parameters
#### Request Body
- **rootFolder** (string) - Required - Absolute path on disk to serve
- **indexPath** (string) - Required - Path of index file, relative to root folder
- **args** (string[]) - Required - Command-line arguments, to pass as global.Itch.args
- **env** ({ [key: string]: string }) - Required - Environment variables, to pass as global.Itch.env

### Result
none
```

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

### ShellLaunch

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Requests the client to perform a shell launch, opening a specified item with the operating system's default handler. This is typically used to open files or directories in the file explorer.

```APIDOC
## ShellLaunch (client caller)

### Description
Ask the client to perform a shell launch, ie. open an item with the operating system’s default handler (File explorer). Sent during Launch.

### Parameters
#### Request Body
- **itemPath** (string) - Required - Absolute path of item to open, e.g. D:\Games\Itch\garden\README.txt

### Result
#### Success Response
(none)
```

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

### Queue and Perform Game Update

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Queues an update for a game and then performs it using the Install.Perform flow. Butler uses wharf patching for efficient transfers when build metadata is available.

```Go
client.Install.Queue(caveId, "update")
client.Install.Perform()
```

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

### Check for Game Updates

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Checks for available updates for installed games. Can scope to specific games by providing cave IDs.

```Go
client.CheckUpdate(caveIds...)
// The result is an array of GameUpdate records.
```

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

### Fetch.DownloadKeys

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Fetches multiple download keys from the local database or via an API request. Supports filtering, pagination, and forcing a fresh API call.

```APIDOC
## Fetch.DownloadKeys

### Description
Fetches multiple download keys. This operation can retrieve keys from the local database or force an API request for fresh data. It supports pagination and filtering.

### Method
(Not specified, likely a client-side SDK method)

### Parameters
#### Path Parameters
(None specified)

#### Query Parameters
(None specified)

#### Request Body
- **profileId** (number) - Required - The ID of the profile to fetch download keys for.
- **offset** (number) - Optional - Number of items to skip for pagination.
- **limit** (number) - Optional - Maximum number of results per page. Defaults to 5.
- **filters** (FetchDownloadKeysFilter) - Optional - Criteria to filter the download keys.
- **fresh** (boolean) - Optional - If true, forces an API request instead of using cached data.

### Request Example
(No example provided in source)

### Response
#### Success Response
- **items** (DownloadKey[]) - An array of download keys found.
- **stale** (boolean) - Optional - Indicates if the information was fetched from a stale cache.

#### Response Example
(No example provided in source)
```

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

### Find Butler Executable Path

Source: https://github.com/itchio/butler/blob/master/docs/installing.md

Prints the full path to the butler executable. Use this command if you forget where you installed butler.

```sh
butler which
```

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

### Previewing Push Changes

Source: https://github.com/itchio/butler/blob/master/docs/pushing.md

Use the `butler push-preview` command to compare a local directory with the previous build of a channel. It reports which files would be added, modified, deleted, or remain unchanged without actually pushing.

```APIDOC
## butler push-preview

### Description
Compares a local directory against the previous build of a specified channel to show what changes would occur during a `butler push`. It classifies each file as NEW, MODIFIED, DELETED, or SAME.

### Command
```bash
butler push-preview <source_directory> <target_channel>
```

### Parameters
*   **source_directory**: The local directory containing the build files to compare.
*   **target_channel**: The target channel in the format `user/game:platform-distribution`.
*   **--changes-only**: Optional flag to hide unchanged entries from the listing, useful for large builds.

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

### Example with --changes-only
```bash
butler push-preview --changes-only my-game user/mygame:win-64
```

### Output Example
```
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
```

### Notes
*   If the channel has no previous build, all entries are reported as `NEW`.
*   This command accepts walk-related flags from `butler push` like `--dereference`, `--fix-permissions`, `--auto-wrap`, and `--ignore`.
*   Build creation flags like `--userversion` and `--hidden` are not applicable as `push-preview` does not create builds.
```

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

### Downloads.Prioritize

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Puts a download at the top of the queue.

```APIDOC
## Downloads.Prioritize

### Description
Puts a download at the top of the queue.

### Parameters
#### Request Body
- **downloadId** (string) - Required - Description

### Result
#### Success Response
*none*
```

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

### Log in to itch.io account

Source: https://github.com/itchio/butler/blob/master/docs/login.md

Run this command to authenticate with your itch.io account. Butler will prompt you to log in if you haven't already.

```bash
butler login
```

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

### butlerd Listen Notification Structure

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Example JSON structure of a butlerd listen notification, containing connection details like secret and TCP address.

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

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

### Identify file type and get information

Source: https://github.com/itchio/butler/blob/master/docs/offline.md

Use `butler file` to determine if a file is a patch or signature file and retrieve general file information.

```bash
butler file <file>
```

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

### Fetch.GameRecords

Source: https://github.com/itchio/butler/blob/master/butlerd/generous/docs/README.md

Fetches game records, including owned, installed, and collection games, with support for search, filtering, and sorting. It includes download key and cave information.

```APIDOC
## Fetch.GameRecords

### Description
Fetches game records - owned, installed, in collection, with search, etc. Includes download key info, cave info, etc.

### Method
N/A (Client Request)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **profileId** (number) - Required - Profile to use to fetch game
- **source** (GameRecordsSource) - Required - Source from which to fetch games
- **collectionId** (number) - Optional - Collection ID, required if source is "collection"
- **limit** (number) - Optional - Maximum number of games to return at a time
- **offset** (number) - Optional - Games to skip
- **search** (string) - Optional - When specified only shows game titles that contain this string
- **sortBy** (string) - Optional - Criterion to sort by
- **filters** (GameRecordsFilters) - Optional - Filters
- **reverse** (boolean) - Optional - 
- **fresh** (boolean) - Optional - If set, will force fresh data

### Request Example
```json
{
  "profileId": 123,
  "source": "owned",
  "limit": 10,
  "search": "MyGame"
}
```

### Response
#### Success Response (200)
- **records** (GameRecord[]) - All the records that were fetched
- **stale** (boolean) - Optional - Marks that a request should be issued afterwards with ‘Fresh’ set

#### Response Example
```json
{
  "records": [
    {
      "id": 12345,
      "title": "My Awesome Game",
      "installed": true
    }
  ],
  "stale": false
}
```
```

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

### Typical Launcher Lifecycle - Shutdown

Source: https://github.com/itchio/butler/blob/master/docs/launcher-integration.md

Manages the graceful shutdown of the launcher, including closing the connection to the Butler daemon.

```Go
# close the TCP connection; --destiny-pid will reap the daemon
```

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

### Preview Push Changes

Source: https://github.com/itchio/butler/blob/master/docs/pushing.md

Use the butler push-preview command to compare a local directory against a channel's previous build. It reports which files would be added, modified, deleted, or left unchanged without actually pushing.

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