# Butler Deploy

> >

- **Type:** Skill
- **Install:** `agentstack add skill-yesterday-ai-skills-butler-deploy`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Yesterday-AI](https://agentstack.voostack.com/s/yesterday-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Yesterday-AI](https://github.com/Yesterday-AI)
- **Source:** https://github.com/Yesterday-AI/skills/tree/main/plugins/systems-operations/skills/butler-deploy
- **Website:** https://github.com/Yesterday-AI/skills

## Install

```sh
agentstack add skill-yesterday-ai-skills-butler-deploy
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Butler Deploy

Push HTML5 game builds to itch.io with the [butler CLI](https://itchio.itch.io/butler).
Butler does delta uploads (only changed files after the first push) and the
game is live the moment the push completes.

## When to use

- First-time publish of a web build to itch.io
- Updating an existing itch.io page with a new build
- Wiring an itch.io deploy step into CI

## Prerequisites

### 1. Install butler (one-time, per machine)

```bash
# macOS
brew install butler

# Linux
curl -L -o butler.zip https://broth.itch.ovh/butler/linux-amd64/LATEST/archive/default
unzip butler.zip
mv butler /usr/local/bin/butler

# Windows
scoop install butler
# or download from https://itchio.itch.io/butler
```

### 2. Authenticate (one-time, per machine)

```bash
butler login
# Opens browser → authorize → return to terminal.
```

For CI: set `BUTLER_API_KEY` instead (generate at
). No `butler login` needed.

### 3. Create the itch.io page (one-time, in browser)

Butler refuses the first push if the target page does not exist.

1.  → **Create new project**
2. Settings:
   - **Kind:** HTML
   - **Viewport size:** match your build (e.g. 1280×720)
   - **"This file will be played in the browser"**: checked
3. Save as **Draft** (publish after verifying the first push).

After the page exists, all future deploys are fully scripted.

## Core command

```bash
butler push  /: --userversion 
```

| Argument | Example | Meaning |
|----------|---------|---------|
| `` | `dist/` | local directory to upload |
| `/` | `acme/spacelander` | itch.io target |
| `` | `html5` | upload channel (`html5`, `windows`, `linux`, `osx`, …) |
| `--userversion` | `1.4.2` | stamps the upload (optional but recommended) |

Example:

```bash
butler push dist/ acme/spacelander:html5 --userversion 1.4.2
```

## Common patterns

### Build then push

Wire build + push together — pick whichever fits your stack:

```bash
# Direct
npm run build && butler push dist/ acme/spacelander:html5 --userversion "$(node -p "require('./package.json').version")"

# Make
make build && butler push build/web acme/spacelander:html5

# Project npm script (optional convenience)
# package.json: "deploy": "butler push dist/ $ITCH_GAME:html5 --userversion $npm_package_version"
ITCH_GAME=acme/spacelander npm run deploy
```

### Channel-per-platform

```bash
butler push dist/web    acme/spacelander:html5
butler push dist/win    acme/spacelander:windows
butler push dist/linux  acme/spacelander:linux
butler push dist/osx    acme/spacelander:osx
```

### Verify after push

```bash
butler status acme/spacelander            # all channels, latest version + state
butler status acme/spacelander:html5      # one channel
```

## Useful butler commands

```bash
butler login                              # interactive auth (browser)
butler logout
butler push  /: [--userversion VER] [--ignore PATTERN]
butler status /[:]
butler fetch  /:    # download a build
butler validate                      # sanity-check a build dir
butler --version
```

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `butler: command not found` | not installed | install per step 1 |
| `404 Not found` on first push | itch.io page doesn't exist | create the project page in browser first |
| `401 Unauthorized` | not logged in / bad API key | `butler login`, or fix `BUTLER_API_KEY` |
| `403 Forbidden` | account doesn't own the target | check `/` slug matches a project you own |
| Push silently uploads everything every time | `dist/` content non-deterministic (timestamps, build hashes) | rebuild with stable filenames, or `--ignore` volatile files |
| `--userversion` shows up empty on itch.io | flag value missing/empty | confirm the version env / `package.json` field is set before invoking |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Yesterday-AI](https://github.com/Yesterday-AI)
- **Source:** [Yesterday-AI/skills](https://github.com/Yesterday-AI/skills)
- **License:** MIT
- **Homepage:** https://github.com/Yesterday-AI/skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yesterday-ai-skills-butler-deploy
- Seller: https://agentstack.voostack.com/s/yesterday-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.