How to Use itch Butler in the App - First GUI Upload Evening 2026

If you are searching itch butler, you may not want another CLI wall of user/game:channel. You want a Monday path: open the itch desktop app, use the Upload sidebar, push a folder or zip to a named channel, preview the patch, and decide keep or hold before players download the wrong build.

On May 18, 2026, itch.io announced that pushing builds with butler is now in the itch app—a friendly GUI that wraps the same patching pipeline as the command line, without requiring a terminal.Official update The butler manual now points creators who prefer GUI to the app (v26.12.0 or later) for uploads, change previews, and build management.Butler intro Installing butler

Who this is for: beginners who never ran butler push, creators shipping jam builds, and indie leads who want a human-owned upload ritual before CI automation.
Time: 60–120 minutes for a first GUI push on a throwaway or beta channel.
Honest limit: the GUI is for interactive pushes. Headless CI, API keys in GitHub Actions, and scripted multi-channel matrices still belong on the CLI—use the ninety-minute Butler + store QA pass when you need terminal discipline and store-page truth tables.

Non-repetition: This is not the terminal-first QA checklist. It is not the Sale Explorer / Bundle Hosting / Patreon changelog. It is not the itch–Steam dual depot dress rehearsal. Same storefront family—different job.

Why this matters now

1. Butler stopped being “terminal only.” Official docs and the May update make the Upload tab a first-class path for creators who were stuck uploading giant browser zips or avoiding patches entirely.Announcement
2. Upload season is continuous. July 2026 Sale Explorer and bundle tooling keep itch discovery busy; dual Steam+itch teams still need clean channels before October peaks.Sale Explorer playbook
3. SERP is announcement-heavy. The update explains the Builds page; it does not ship an indie I1–I6 keep/hold with channel map, patch-preview traps, multi-profile auth, and explicit handoff to CLI/CI. That gap is this URL.

Parent demand stays enormous under itch.io organic search (Semrush-class snapshots put organic traffic in the multi-million range). The desktop app itself sits at thousands of GitHub stars—the same binary that now ships the Upload UI.

What the GUI is (and is not)

Butler still works the same underneath: first push sends the build; later pushes send patches (what changed). Players on the itch app download patches instead of whole games when possible.Announcement Pushing builds

Prerequisites

• [ ] itch.io account that can edit the target project.
• [ ] itch desktop app v26.12.0 or later (Preferences → check for updates if Upload is missing).Announcement
• [ ] A smoke-tested Windows/macOS/Linux folder or zip—not “the build we probably made yesterday.”
• [ ] Written channel map (example: windows public, windows-beta hidden/QA).
• [ ] Named session owner who will file the receipt.
• [ ] Optional: second clean machine or fresh download folder for the post-push install smoke.

If Upload is missing, you are on an old app build—update first; do not “fix” it by pasting CLI you do not understand yet.

Beginner path - first GUI push in one evening

Step 1 - Update the app and open Upload

1. Launch the itch app and sign in.
2. Confirm version ≥ 26.12.0.
3. Open the Upload entry in the sidebar → Builds page.

You should see rows for builds on projects you can edit: project, channel, version, status, size, pushed time. Filter by Live / Processing / Failed; search by project, channel, or version.Announcement

Step 2 - Freeze the artifact (10 minutes)

Write on a sticky note:

Version: 0.3.1
Git: abc1234
Folder/zip path: D:\Builds\MyGame-windows\
Channel tonight: windows-beta (not public windows yet)

The GUI cannot save you from pushing the wrong folder. That is still a human gate.

Step 3 - Push dialog - project, channel, source

Click Push new build:

1. Pick the project.
2. Choose a channel or type a new kebab-case name (windows-beta, linux-arm64, macos-preview).
3. Optionally set a user version (your semantic version).
4. Drop a folder or .zip.
5. Use recent folders when you re-push the same export path often.

Channel names hint platform tags (win/windows, linux, mac/osx, android). You can fix tags later on Edit game—but starting clean avoids player confusion.Pushing builds

Step 4 - Run patch preview before you commit

Before the real push, generate the preview of what changed since the last build on that channel: new / modified / deleted / unchanged counts, sizes, and largest changed files.Announcement

Beginner checkpoint: if preview shows your entire Library/ or a gigabyte of .pdb files as NEW, hold. Fix the export folder. On CLI this is butler push-preview; the GUI is doing the same job with less typing.Push preview docs

Step 5 - Push and watch status

Start the push. Track phase (preparing, diffing, uploading, finishing), bytes, patch size, ETA. Expand the build row afterward to audit associated files, whether an optimized patch is still processing, and the copyable CLI command if you want to mirror the push later from a terminal.Announcement

Remember: default patch can go live while the backend still optimizes the patch (sometimes ~30 minutes on large games). Players are not blocked waiting for optimization.Pushing builds

Step 6 - Download your own build once

In a clean folder (or another profile), install/download the channel you just pushed. Launch once. If controls or README claim features the zip does not have, fix the page or the zip before you unhide.

Step 7 - Optional - copy the CLI twin

Expand the successful Builds row and copy the equivalent butler push command when the UI offers it. Paste it into your team notes. That is how a beginner GUI evening becomes a CI ticket tomorrow without reinventing the channel string.Announcement

Builds page - what each column is for

Treat the Builds list like a flight board, not a decoration.

Filter Failed every Friday. A silent Failed row is how press gets last week’s build while Slack thinks you shipped.

Export folders that survive a GUI push (Unity and Godot)

The Upload dialog does not magically exclude caches. Prepare a release directory the same way CI would.

Unity (Windows example)

• Push the player build folder (exe + _Data / IL2CPP siblings), not the entire Unity project.
• Strip or never export .pdb into the folder you drop into the dialog.
• Confirm x64 vs ARM matches the channel name story you tell players.

Godot 4

• Push the export preset output directory, including .pck / .exe (or macOS .app bundle) as your preset defines.
• Include GDExtension native libraries next to the binary when the preset requires them.
• Do not drop the whole res:// project tree into Upload “because it is easier.”

Zip vs folder

• Folder pushes are fine when the tree is already the player payload.
• A single .zip inside an otherwise empty folder may be auto-unpacked by butler (CLI documents auto-unzip)—know whether you intend nested zip behavior before you blame “itch ate my archive.”Pushing builds

Browser upload vs GUI butler vs CLI - decide in thirty seconds

If you re-upload a 2 GB game through the browser every hotfix, you are burning your evening and your players’ bandwidth. Switch to GUI or CLI butler the same week you ship the second build.

Jam night playbook (90 minutes on the clock)

1. T−90: Freeze artifact + channel map (jam-windows, not windows if you might iterate).
2. T−70: App update check; open Upload; confirm profile.
3. T−60: Push dialog + preview; fix folder if preview screams.
4. T−40: Push; watch Live/Processing.
5. T−25: Clean download smoke; fix README lies.
6. T−10: Unhide or flip page visibility only if I1–I6 pass.
7. T−0: Paste build id / user version into the jam submission form and your dual-Steam sheet if needed.

Do not invent a new channel name under panic. Panic invents final-final-2.

Developer path - channels, hidden builds, CI handoff

Channel map (write it once)

kebab-case only. Do not invent Windows Final!!! as a channel name.

Hidden channels from the GUI

The app supports pushing new builds as hidden so they are not visible to end users immediately.Announcement CLI equivalent is butler push ... --hidden on first push to a new channel—later hidden patches on existing channels are not supported the same way; read the flag rules before you assume.Hidden pushes

Keep/hold: use hidden for brand-new QA channels. Do not treat --hidden as a general “secret patch” switch on busy public channels.

Multi-profile auth

The GUI pushes with the logged-in itch app profile. Switching profiles is how you manage studio vs personal accounts without juggling API keys in a shell.Announcement

Company rule: name which profile owns retail windows. Contractors get a QA profile that can only see beta projects.

When CLI / CI still wins

Expand a Builds row to copy the equivalent CLI command when you are ready to automate the same channel.Announcement

HTML5 / browser games caveat

Tagging a channel as HTML5 / playable in browser still needs Edit game settings after the first push, and the page type must be HTML—not only “downloadable.”Pushing builds Pair with browser demo scope discipline before you treat HTML5 as free marketing.

Size and processing honesty

Backend rejects builds whose total uncompressed size exceeds 30GB.Pushing builds If your “indie zip” is pathologically huge, fix Addressables/export settings before blaming the Upload tab.

Gates I1–I6 (GUI latch)

Latch itch_butler_gui_ok only when all six pass. Receipt example: itch_butler_gui_upload_receipt_v1.json.

If any gate fails, hold unhide / public channel promotion.

Example receipt

{
  "receipt": "itch_butler_gui_upload_receipt_v1",
  "project": "user/my-game",
  "channel": "windows-beta",
  "user_version": "0.3.1",
  "app_version": "26.12.x",
  "preview_ok": true,
  "hidden_or_restricted": true,
  "gates": { "I1": true, "I2": true, "I3": true, "I4": true, "I5": true, "I6": true },
  "owner": "session-owner-name",
  "notes": "GUI push only; retail windows channel held."
}

Failure modes and quick fixes

Company / diligence notes

• Ownership: one person owns channel map; one person owns retail unhide.
• Cost/ROI: GUI reduces jam-night support tickets from “how do I install butler?”; CI still saves engineer hours at scale.
• Security: profile switch discipline; no shared personal login on a contractor laptop without a wipe policy.
• Audit: keep receipts with build IDs / user versions next to Steam build IDs when dual-shipping.
• Governance: forbid silent pushes to public windows without I4 preview screenshots in the release thread.

How this fits a micro-studio week

Monday: I1–I6 on windows-beta only.
Tuesday: Fix store short text if smoke fails claims.
Wednesday: Promote to public windows after another preview.
Thursday: Copy CLI command into Actions for one OS.
Friday: Align itch user version with Steam build id in one spreadsheet row.

Common mistakes

1. Pushing retail channel on night one — start beta/hidden.
2. Skipping preview — that is how Library folders ship.
3. Confusing browser upload with butler — no patch savings.
4. Assuming Processing means broken — default patch may already be live.
5. One channel for win+mac+linux mess — split OS channels unless you truly ship a universal payload.
6. Ignoring the existing CLI QA checklist when CI arrives — GUI does not replace store-page truth.
7. Treating HTML5 as automatically tagged — Edit game still required.
8. No clean download smoke — you only tested the export folder on the build machine.

Key takeaways

1. itch butler now ships a GUI in the itch app Upload / Builds tab (v26.12.0+).
2. Same patching benefits as CLI—without requiring a terminal for human pushes.
3. Always preview before push; treat surprise NEW trees as a hold.
4. Use a written channel map; do not improvise retail names.
5. Hidden helps new QA channels; know the flag limits.
6. Multi-profile auth beats sharing one personal login.
7. Latch itch_butler_gui_ok only on I1–I6.
8. Hand off to CLI/CI when you need matrices, ignore patterns, or API keys.
9. Pair with Butler ninety-minute QA for store-page + zip discipline.
10. Keep discovery changes in view via Sale Explorer playbook.

FAQ

What is itch butler in the app?

The itch desktop app’s Upload / Builds UI that runs butler under the hood so you can push folders or zips to project channels, preview patches, and manage build status without a terminal.Announcement

Which itch app version do I need?

At least v26.12.0 for the Upload tab.Announcement

Is the GUI the same as butler push?

Same patching pipeline and credentials-of-the-logged-in-profile model; CLI still exposes flags (ignore, dereference, if-changed, dry-run) and CI auth the GUI is not trying to replace.Butler docs Pushing

Can beginners finish a safe first upload in one evening?

Yes if you push a beta/hidden channel, run preview, and smoke-download once. No if you aim to rewrite all CI and unhide retail the same night.

Should I still learn the CLI?

Yes before you automate. Use the GUI to learn channels and previews; use the ninety-minute QA pass when store copy and CI keys matter.

Why is my build stuck on Processing?

Backend optimized-patch generation can take a while on large builds; the default patch can already be live for players.Pushing builds

How do hidden uploads work in the GUI?

The app supports pushing as hidden so builds are not immediately player-visible; align with butler --hidden rules for new channels and unhide from Edit game when ready.Announcement Pushing

How do I know my channel tags are correct?

Channel names hint Windows/Linux/Mac/Android tags, but you can always adjust checkboxes on the Edit game page and save. Open the green channel button to inspect builds and status after a push.Pushing builds

What if preview shows almost everything as NEW?

You are comparing against an empty or unrelated previous build, or you pointed at a different folder than last time. Confirm channel name, confirm path, and only then push. First push to a brand-new channel reporting everything as NEW is normal.

Related reading

• itch.io Butler upload and store page ninety-minute QA pass
• itch.io Sale Explorer Bundle Hosting and Patreon - What Changed 2026
• Your first itch–Steam dual depot dress rehearsal
• itch pay-what-you-want vs Steam demo SKU economics
• Stop unscoped itch HTML5 “free marketing”

Official sources

• Pushing builds with butler is now in the itch app
• Butler manual
• Pushing builds with butler
• Installing butler