> For the complete documentation index, see [llms.txt](https://gamelauncher.cloud/help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gamelauncher.cloud/help/applications/upload-builds/upload-builds-cli.md).

# Upload with the CLI Tool

The CLI uploads your build directly to Cloudflare R2, so it handles large files and can run inside your CI/CD pipeline.

{% hint style="success" %}
Use the CLI when your build is over the 5 GB dashboard limit, when the upload speed matters, or when you want releases to happen automatically.
{% endhint %}

***

## Before You Start

Your build must be a **.zip** file with all game files **in the root** of the ZIP (not inside a single folder). See [Prepare Your Build](/help/applications/upload-builds.md#prepare-your-build) if you are not sure.

***

## Step 1: Download the CLI

Grab the binary for your platform on the [CLI Download](/help/extensions/cli-releases.md) page. There is no installer: it is a single executable you can run from anywhere.

<figure><img src="/files/izhaFnzG5WD2aVXkZ1fW" alt=""><figcaption><p>Game Launcher Cloud CLI</p></figcaption></figure>

{% hint style="info" %}
The CLI works in two modes: **interactive** (run it with no arguments and follow the menu) or by **commands** (the examples below).
{% endhint %}

***

## Step 2: Log In

```bash
gamelaunchercloud-cli login
```

Pick one of the three methods:

* **Browser (recommended):** opens your browser and returns to the terminal when you are done
* **API Key:** best for CI/CD, create yours at [app.gamelauncher.cloud/user/api-keys](https://app.gamelauncher.cloud/user/api-keys)
* **Email and password**

Credentials are saved locally, so you only do this once per machine.

***

## Step 3: Find Your App ID

```bash
gamelaunchercloud-cli list-apps
```

```
╭─🎮 Applications───────────────────────╮
│ ID │ Name           │ Builds │ Owner  │
├────┼────────────────┼────────┼────────┤
│  1 │ My Game        │ 15     │ You    │
│  2 │ Racing Game    │ 8      │ Team   │
╰────┴────────────────┴────────┴────────╯
```

The list includes your apps and the apps of teams you belong to.

***

## Step 4: Upload the Build

```bash
gamelaunchercloud-cli upload -a 1 -f "MyGame_v1.2.0.zip" -n "Bug fixes and new features"
```

| Option         | Meaning                                        |
| -------------- | ---------------------------------------------- |
| `-a, --app-id` | Application ID from `list-apps`                |
| `-f, --file`   | Path to your ZIP file                          |
| `-n, --notes`  | Build notes, players read them in the launcher |

The CLI requests a presigned URL, uploads straight to Cloudflare R2 (multipart automatically over 100 MB) and then tells the backend to start processing.

```
Step 1/3: Requesting upload URL...
✓ Upload URL obtained (Build ID: #224)

Step 2/3: Uploading to cloud storage...
Uploading... ━━━━━━━━━━━━━━━━━━━━━━━ 100%
✓ Upload completed in 1m 41s
Average speed: 20.34 MB/s

Step 3/3: Notifying backend...
✓ Backend notified successfully
```

Write down the **Build ID** it prints, you need it for the next step.

***

## Step 5: Watch the Processing

```bash
gamelaunchercloud-cli status 224 --watch
```

The status refreshes until the build is done:

`Pending` → `Enqueued` → `DownloadingBuild` → `UnzippingBuild` → `CreatingPatch` → `Completed`

```
╭─📊 Build Status──────────────────────╮
│ Build ID: #224                       │
│ Status: ✅ Completed                  │
│ Compressed Size: 2.01 GB (55% saved) │
│ Upload Duration: 1m 41s              │
│ Total Duration: 5m 6s                │
╰──────────────────────────────────────╯
```

{% hint style="warning" %}
If the build ends in `Failed`, you do not have to upload the file again. Retry it with the file already in storage:

```bash
gamelaunchercloud-cli retry 224
```

{% endhint %}

***

## Step 6: Set the Build as Active

A processed build is not live yet. Activation happens in the dashboard:

{% stepper %}
{% step %}
**Open the Environments tab**

Go to your app and click **"Change Active Build"**.

<figure><img src="/files/jkrJTaGwKKYgkF9X47Ww" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Confirm**

Select the build you just uploaded and click **Set Build**.

<figure><img src="/files/M62sk9jlMRbNRFEBiJbA" alt=""><figcaption><p>Change active build dialog</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**Players update automatically:** once a build is active, players receive it the next time they open the launcher.
{% endhint %}

***

## Automate It

The same flow runs unattended on every release tag. Ready to copy examples for GitHub Actions, GitLab CI and plain bash are in the CLI reference:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>⚙️ CLI Commands</strong></td><td>Full command reference, CI/CD examples and ignored paths</td><td><a href="/pages/ldf8xMmJffACG4lfxUOK">/pages/ldf8xMmJffACG4lfxUOK</a></td></tr></tbody></table>

***

## Troubleshooting

| Problem                     | Solution                                       |
| --------------------------- | ---------------------------------------------- |
| "Not authenticated"         | Token expired. Run `login` again               |
| "App not found"             | Wrong app ID. Check it with `list-apps`        |
| "Upload failed"             | Network issue. Check the connection and retry  |
| Build stuck in "Processing" | Large builds take longer. Use `status --watch` |
| Build ended in "Failed"     | Run `retry <build-id>`, no re-upload needed    |
| "Email not confirmed"       | Verify your email in the dashboard first       |

{% hint style="success" %}
**Need help?** Join [Discord](https://discord.com/invite/FpWvUQ2CJP) or email <support@gamelauncher.cloud>
{% endhint %}

***

## Next Steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>⚙️ CLI Commands</strong></td><td>Every command, option and CI/CD example</td><td><a href="/pages/ldf8xMmJffACG4lfxUOK">/pages/ldf8xMmJffACG4lfxUOK</a></td></tr><tr><td><strong>🌐 Dashboard Upload</strong></td><td>Upload from the browser instead, up to 5 GB</td><td><a href="/pages/nzy3OPBLAD7WQv1oBzUM">/pages/nzy3OPBLAD7WQv1oBzUM</a></td></tr><tr><td><strong>🧩 How Patching Works</strong></td><td>Why players only download what changed</td><td><a href="/pages/G7EDuuyO4kDn9NxT7p7M">/pages/G7EDuuyO4kDn9NxT7p7M</a></td></tr><tr><td><strong>🌍 Environments</strong></td><td>Test in Staging before going to Production</td><td><a href="/pages/Bzo5c15XEsyTL0bEaWsM">/pages/Bzo5c15XEsyTL0bEaWsM</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gamelauncher.cloud/help/applications/upload-builds/upload-builds-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.