# Publish a browser game to Rosebud: instructions for coding agents

Use these steps when a person asks you to put their browser game online with Rosebud's free game hosting. Run them in order. Every `rosebud` command except `--help` and `--version` prints one JSON object: results on stdout, errors on stderr.

To change a game the person made in the Rosebud editor, use [Work on a game the person made in Rosebud](#work-on-a-game-the-person-made-in-rosebud) instead. To make art, audio or 3D models for a game, see [Log in and make assets](#log-in-and-make-assets).

Human-readable guide: [publishing guide](https://rosebud.ai/docs/guides/publish-a-game). Endpoint details: [HTTP reference](http-reference.md).

## 1. Prepare the build

- Build the game if the project has a build step. You will upload the output folder (for example `./dist`), not the source.
- No build step? Copy the files the game needs (`index.html` and everything it loads) into a new folder such as `./dist`, and publish that. Don't publish the project root: the CLI keeps its state in `.rosebud/` there, and hidden files such as `.gitignore` can't be uploaded. Copy the files again before each `rosebud update`.
- The folder must have `index.html` at its top level and run from static files. Rosebud does not run a build or install packages.
- Text files can go anywhere in the folder: HTML, JS, CSS, JSON, Markdown notes such as `AGENTS.md`, license notices and any other UTF-8 file that isn't media. A text file may have any name the Rosebud editor allows, except hidden names (a leading dot), names of only spaces, and names with `< > : " | ? * / \` or control characters. A name is at most 255 characters and a path at most 500.
- Preserve UTF-8 `.txt` notices (including `.TXT`) and extensionless `LICENSE`, `LICENCE`, `NOTICE`, `COPYING`, `COPYRIGHT` and `AUTHORS` at their original paths, with unchanged contents. Their filenames may keep their original case. Never remove license notices to make an upload pass.
- Put every image, audio file, font, model and WASM file inside `assets/`, with lowercase names using letters, numbers, underscores and single hyphens; start and end names with a letter or number, and use dots only for extensions (for example `assets/player-ship.png`). Update the references in your code to match. Media outside `assets/` is refused with `media_path`, and an empty media file with `file_limit`.
- Supported media: PNG, JPEG, WebP, SVG; MP3, WAV, OGG, OGA; WOFF, WOFF2, TTF, OTF; WASM; GLB, glTF and `.bin` buffers. Outside `assets/`, `.svg` and `.gltf` files are text.
- New media names go up in Unicode NFC, with each accented letter as one character. Two names in the folder that are the same name in NFC are refused with `duplicate_path`; keep one.
- Limits:
    - Each file is at most 19 MiB (19,922,944 bytes); a bigger one is refused with `file_limit`. A game has at most 2,000 files (`entry_limit`) and 1 GiB in all (`expanded_limit`).
    - Media goes up file by file, not inside a ZIP. Text files travel in one ZIP of at most 10 MiB compressed, 50 MiB expanded and 500 files.
    - One publish or update adds at most 128 MiB of new media. Over that, the error is `release_upload_limit` and `error.limit` is the exact limit in bytes. Publish with part of the media, then `update` with the rest. Files Rosebud already has, with the same path, size and MD5, are not uploaded again and don't count.
    - `--zip` sends your archive as it is, media included, so all of it must fit the ZIP limits: 10 MiB compressed, 50 MiB expanded and 500 entries, including folders. Use `--directory` for a game with more media than that.
- Everything you upload is public. Keep `.env` files, credentials, `node_modules` and source maps out of the build. Rosebud refuses these names with `excluded_file`: any ending in `.env` (in any case, ignoring surrounding spaces), `credentials`, `secrets`, `credentials.json`, `service-account.json`, `service_account.json`, `node_modules` and anything containing `firebase-adminsdk`. A hidden name such as `.env` is refused as `unsafe_path`. Rosebud also refuses any file that holds a private key.
- `.DS_Store`, `Thumbs.db` and `desktop.ini` are skipped when packing and pulling, never uploaded and never an error. Other hidden files are refused.
- If the game plays sound, give it a mute button and a volume control, and start music quietly. Rosebud's play page has a volume control too, but players look for one in the game.

## 2. Install the CLI

```sh
npm install --global @rosebudai/cli
```

It needs Node.js 22 or later. If you can't install globally, replace `rosebud` in every command below with `npx --yes @rosebudai/cli`.

## 3. Publish once

Run this from the project root, not from inside the build folder:

```sh
rosebud publish --directory ./dist --title 'Moon Garden' --description 'Collect five glowing seeds.'
```

- `--title` and `--description` are optional. Include them: they appear on the play page. Use the game's real name and one plain sentence about it.
- `--thumbnail ./cover.png` is optional: a PNG or JPEG gameplay screenshot, at most 2 MiB.
- `--agent-client` is optional. Set it to `claude-code`, `codex`, `cursor`, `gemini-cli` or `other` to say which tool published the game. `rosebud connect` accepts it too.
- Use `--zip ./game.zip` instead of `--directory` if you already have a ZIP.
- A big game can take minutes: each media file uploads on its own. Allow the time, or run the command in the background.

If you signed in with `rosebud login` and `rosebud whoami` reports `"status": "active"`, the game goes straight into that person's account. The result has `"claimed": true`, `owner` and `editor_url` instead of claim fields, and `rosebud update` works at once: skip the connect and claim steps in step 5. If Rosebud couldn't add the game to the account, the result has the claim fields below instead; hand off as step 5 says. A login that still waits for approval fails with `login_pending`; finish it, or run `rosebud logout` to publish with a claim link.

Without a login, the result includes `play_url`, `claim_url` and `claim_expires_at`. The one-hour claim window starts now. The CLI saves the game's handle in `.rosebud/project.json`; if the project uses git, add `.rosebud/` to `.gitignore`.

Each `publish` creates a new game, so don't publish again to retry an error. If a publish exits with code 4, the game may already exist: tell the person instead of publishing again.

## 4. Check the game

Open `play_url` in a browser and confirm the game loads and responds to input. A successful upload means the files were accepted, not that the game works. If you can't open a browser, fetch `play_url` to confirm the page exists, then say so when you hand off and ask the person to check that the game runs. The game loads in the browser, so fetching the page doesn't prove it works.

If the game doesn't start, fix the build and publish it again as a new game with its own state file, for example `--state .rosebud/fixed.json`, and pass that `--state` to every later command. Hand off only the new game's links. Nobody can claim the broken upload without its link, so it's deleted after an hour.

## 5. Hand off to the person

If the publish result had `"claimed": true`, give the person the `play_url` (public, shareable) and the `editor_url`, and say the game is already in their account. There is nothing to claim or approve. Skip the rest of this step.

Otherwise, unless the person has said they don't want you to publish updates, run:

```sh
rosebud connect
```

Give them the `approval_url` it prints. Opening it claims the game and lets you publish updates, in one step. It expires after 30 minutes.

Also give them the `claim_url` from step 3 as a backup. It keeps working until `claim_expires_at`, so they can still keep the game if the approval link has expired. Once the game is claimed, the claim link stops working, but the approval link still works for the account that claimed it until it expires. Later, `rosebud connect` creates a new approval link for the owner.

If they don't want you to publish updates, give them only the `claim_url`.

Tell them:

1. The play link. It's public and they can share it.
2. The approval link and the claim link. They're private: anyone with either can claim the game.
3. The deadline from `claim_expires_at`, in their time zone if you know it, otherwise in UTC. The unclaimed game becomes unavailable at that time and is permanently deleted by background cleanup.
4. What happens next: they open the link, sign in or create a free Rosebud account, and select **Claim game and allow updates** (or **Claim game**).

Don't copy private links into commits, issues, shared logs, chat channels or the game itself.

## 6. Publish updates in later sessions

```sh
rosebud status
rosebud update --directory ./dist
```

- `update` works only when `status` reports `"status": "active"`. If it reports `pending`, `expired` or `revoked`, run `rosebud connect` and ask the person to approve the new link.
- If `content_version` in `status` differs from `saved_content_version`, the game was changed on Rosebud since your last sync. Don't overwrite it. Tell the person, then follow [When Rosebud changed the game](#when-rosebud-changed-the-game): pull their changes, merge them, and only then update with `--expected-version`.
- If an update exits with code 4, run the identical command again, with the folder unchanged. It won't publish twice, and it sends the media the way the first attempt did. If the folder or the options changed meanwhile, `update` refuses with `pending_operation`.
- Omitted `--title`, `--description` and `--thumbnail` keep their current values.
- `update` makes the game exactly the folder you give it: a file Rosebud has that the folder lacks is removed from the game. Files Rosebud already has are not uploaded again.

## If the claim deadline passes

The game is gone and can't be restored. Publish the same local build as a new game with a new state file, then hand off again:

```sh
rosebud publish --directory ./dist --state .rosebud/new-project.json --title 'Moon Garden'
```

Pass that `--state` to every later command for the new game. It has a new link.

## Work on a game the person made in Rosebud

Use this when the game was built in the Rosebud editor, not from your local build. Ask for its project ID, which is in the editor's address: `https://rosebud.ai/edit/<project_id>`.

```sh
rosebud connect --project <project_id>
# The person opens the approval_url, signs in and approves.
rosebud status
rosebud pull --directory ./game
# Edit the files in ./game.
rosebud update --directory ./game
```

1. `connect --project` prints a private `approval_url`. Give it to the person, who signs in as the game's owner and approves access to this one game. It expires after 30 minutes. A public project ID alone grants nothing.
2. Run `rosebud status`. It reports `"status": "active"` once they have, and saves the game's current version.
3. `rosebud pull --directory ./game` writes the game's current files, including edits made in Rosebud, into `./game`. Text files and media both come down, and the folder is created if needed. Use a folder that holds only the game: `update` refuses hidden files such as `.git`, and pull's `next_action` names any it finds.
4. Read the files before you change them. Games made in Rosie include `AGENTS.md` and other notes worth reading first.
5. Edit the files. Keep new media in `assets/` with names that follow step 1.
6. `rosebud update --directory ./game` releases your version to the same link. Titles, descriptions and covers you don't pass keep their values.

Things to know:

- Rosebud keeps media the editor accepts but an update can't upload, such as an MP4, GIF, WebM, M4A, FBX or OBJ, only if you leave the file in place, unchanged, at the same path. Changing or renaming one is refused (`unsupported_file`); do that in the Rosebud editor, then pull again.
- A file Rosebud already holds keeps its type and Rosebud's spelling of its name. Media it serves is sent as media whatever its name, and a file it holds as text, such as an `assets/icon.svg` that Rosie wrote, stays text. A name your folder spells in another Unicode form goes up under Rosebud's spelling. The CLI learns all this from your last `publish`, `update` or `pull`.
- Pull skips a name the disk can't keep (on Windows, one ending in a dot or space, or a device name such as `con.js`) and lists it in `skipped` as `unsafe_path`. Your next update removes it from the game unless the person renames it in Rosebud first.

### If pull fails with plan_required

Reading files back is code download, which needs Rosebud Pro or higher on the game owner's account, and the game must be claimed. Without that, `pull` fails with `plan_required` (exit 3), and its message says the owner's current plan doesn't include it. `publish` and `update` still work, but you can't see what changed in Rosebud. Before you update, ask the person what they changed in Rosebud since your last release, and don't update until they've answered, so you don't replace their edits. Don't create a second game to get around it.

If `pull` fails with `sync_unavailable` (exit 3), this Rosebud server can't read files back yet. Nothing was changed. Treat it the same way, and try again later.

## When Rosebud changed the game

Edits made in the Rosebud editor, changes by Rosie and releases from another agent make your saved version stale. `rosebud status` shows Rosebud's `content_version` and your `saved_content_version`. An `update` against a stale version is refused with `version_conflict` (exit 3) and changes nothing. The error's `changed_paths` says what changed:

| `changed_paths` | Meaning                                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| A list of paths | Rosebud changed, added or removed exactly these files since your last sync (up to 4,000 paths).                           |
| `[]`            | No file changed. Only the game's title, description, cover or published copy did.                                         |
| `null`          | Rosebud can't tell which files changed. It has no record of your version, for example one you learned only from `status`. |
| Missing         | This Rosebud server doesn't report changed files.                                                                         |

`next_action` says what to do and names up to ten paths. Don't overwrite the changes, and don't pass `--expected-version` for a version you haven't merged against.

1. Run `rosebud pull --directory ./dist`, naming the folder you update from. Pull takes the files Rosebud changed, removes the ones it deleted and keeps your own edits, including files only you changed.
2. Pull's result lists `written` and `removed` paths, your `local_only` files, `missing_locally`, `conflicts` and `skipped`, with a `status` of `synced` or `conflicts` and a `next_action`. A file changed on both sides is a conflict. Pull leaves your copy in place, lists it under `conflicts` with a `reason` and a `rosebud_copy` path, and saves Rosebud's copy in a `.remote` folder beside the state file (`.rosebud/project.remote/` for the default state). That folder is outside your build folder, so `update` never uploads it. Pull empties it each time, so merge into your own files, not inside it.
3. Merge each conflict into your file, keeping both changes. A `both_changed` file changed on both sides. For `local_deleted`, which you deleted and Rosebud changed, restore it from Rosebud's copy or leave it deleted. For `remote_deleted`, which Rosebud deleted and you changed, there is no copy: keep the file to restore it, or delete it.
4. Release the merged result, naming the version you merged against:

```sh
rosebud update --directory ./dist --expected-version <content_version from pull or status>
```

Related behavior:

- Pull doesn't move your saved version while conflicts remain. Until a pull reports none, or you pass `--expected-version`, `update` refuses with `pull_conflicts` (exit 2), even when the saved version is already Rosebud's.
- For a conflict that only touched the title, description or cover (`changed_paths` is `[]`), run `rosebud status` and pass its `content_version` as `--expected-version`.
- `missing_locally` lists files that Rosebud and your last sync have but the folder lacks. Whether you deleted them on purpose or lost them, your next update removes them from the game unless you restore them. `rosebud pull --force` restores them.
- `rosebud pull --force` also settles conflicts Rosebud's way: it takes Rosebud's version of each conflicted file and discards your edit. It never touches edits or new files made only on your side. `rosebud update` has no force option and never merges for you.
- The last sync belongs to the folder it happened in. Pulling into another folder, or into an empty or missing one, writes all of Rosebud's files. An `update` from a different folder than the last sync's is refused with `directory_mismatch` (exit 2), because releasing it as it is would undo what that sync brought in. Pull into the folder first, or pass `--expected-version` to release it anyway.
- If the game has a build step, pull into a new, empty folder such as `./rosebud-files`, copy the changes into your source, rebuild, and release the build with `--expected-version <content_version from the pull>`.
- A local name that differs from Rosebud's only by Unicode form (an accented letter as one character or two) is the same file on every system, as it is to Rosebud. One that differs only by letter case is the same file where the disk treats it so, by default on macOS and Windows. Either way your edits to it are kept. Pull never lets one name replace another. Rosebud's `foo.js` against your `Foo.js` is a `case_conflict`. Two Rosebud names that would land on one file or folder here (`Foo.js` and `foo.js`, `Scripts/` and `scripts/`) are each a `name_collision`, and pull writes neither. `clashes_with` names the other side, Rosebud's copies go to the `.remote` folder, and `next_action` says what to rename. `--force` settles a `case_conflict` only when Rosebud renamed a file you had synced by letter case: it takes Rosebud's name and version and discards your edits to the file, as with any conflict. It never replaces a file of your own under another case, and never settles a `name_collision`: rename first.

## Log in and make assets

`rosebud login` connects the CLI to the person's Rosebud account without an API key to copy. A login pays for game assets with the person's credits, and it lets `rosebud publish` put new games straight into their account.

```sh
rosebud login --agent-client claude-code
rosebud whoami
```

- `login` prints a private `approval_url`. Give it to the person, who signs in and approves this agent once. It expires after 30 minutes. `--name <label>` (at most 80 characters) is an optional label, so the person can tell this login apart from their other agents when they approve it.
- `whoami` reports whether the login is `pending`, `active`, `expired` or `revoked`, its `scopes` and `expires_at`, and the person's credit balance. Continue only when it reports `"status": "active"`.
- `login` reports an existing pending or active login instead of replacing it. Run `rosebud logout` first to switch accounts.
- Keep the login while you work: assets and publishing into the account need it. `rosebud logout` revokes it and removes it from this computer, so run it only to switch accounts or when the person asks.
- A login covers the person's assets and asset generation, paid from their credits, and publishing new games into their account. It can't change billing or manage the account.
- A login lasts while it is used: it expires after 90 days without use, and ends when the person disconnects it in Rosebud or you run `rosebud logout`.
- After `key_expired`, run `rosebud login` again. After `insufficient_scope`, which names the `required_scope`, run `rosebud logout`, then `rosebud login`. Both errors carry a `next_action`; for `assets create`, it says to rerun the identical command once the person approves the new login.
- Logging out, or a login that expires, doesn't disconnect games it published. Each game's update connection is separate and lasts until its own 90 days run out or `rosebud disconnect` revokes it.

Choose a model, check the price, then make the asset:

```sh
rosebud assets models --category image
rosebud assets quote --model rosebud-image --prompt 'Mossy stone tile, top-down' --input asset_type=sprite
rosebud assets create --model rosebud-image --prompt 'Mossy stone tile, top-down' --input asset_type=sprite \
  --max-credits 500 --out ./dist/assets/stone-tile.png
```

- `assets models` lists each model's inputs, price and license. `--category` narrows it to `image`, `skybox`, `model_3d`, `video`, `sound_effect`, `music` or `speech`. `--prompt` fills the model's `prompt` input, `--input name=value` sets any other input it lists, and `--input-json ./input.json` supplies inputs as one JSON object.
- Quotes are free. Always pass `--max-credits`: `create` refuses a higher quote before anything is charged. `create` waits up to `--timeout-ms` (default 600000) and saves the file to `--out`. It never replaces an existing file unless you pass `--force`.
- `--no-wait` returns the job at once. Check it with `rosebud assets status <job_id>`, and save its file with `rosebud assets download <asset_id> --out <path>`. `rosebud assets list` searches the person's assets with `--query` and `--category`.
- Credits are charged when a job starts and returned if generation fails. A failed job exits 3 with the reason.
- After an uncertain result (exit 4), including a wait that ran out, rerun the identical command. It resumes the same job and won't pay twice. Once a create has finished, the same command makes a new asset.
- Requests that Rosebud throttles wait out its `Retry-After` and are sent again, for up to a minute. A longer wait fails with `throttled` and `retry_after_seconds`.

The [asset instructions](https://rosebud.ai/developer-assets/AGENTS.md) cover choosing models and what each one returns.

## Rules

- When an update fails, run `rosebud status` before doing anything else. Don't create a second game to work around an error.
- Run commands one at a time, always against the same state file.
- Don't edit files in `.rosebud/` or `~/.config/rosebud/credentials`. Set `ROSEBUD_CREDENTIALS_DIR` to keep credentials in another folder.
- Don't release over changes the person made in Rosebud. Pull and merge them first, or ask the person.
- A command stopped with Ctrl+C or SIGTERM releases its lock and exits 130 or 143 with the error code `interrupted`. A lock left by a process that no longer runs is taken over by the next command, so you can rerun after a timeout.
- Rerunning an interrupted `update`, `pull` or `assets create` is safe and finishes the work. An interrupted `publish` may already have created the game, so check before publishing again.
- When Rosebud is too busy to start a request, it answers `busy` (exit 3, `outcome` `rejected`) and changes nothing. Run the same command again after `retry_after_seconds`, or shortly if there is none. You may change your files first, unless an earlier update is still uncertain. A first `publish` refused as busy created nothing.
- For a large game, Rosebud may first check the files it already has and answer `upload_retry`. The CLI asks again by itself while Rosebud's `remaining` count keeps falling, so the command just takes longer, sometimes several minutes. Nothing is released meanwhile. If it stops with a `next_action` to run the same command again, do that.
- A request that Rosebud throttles (HTTP 429) waits out its `Retry-After` and is sent again, for up to a minute in all. A publish or update request is never sent again on its own.

## Exit codes and common errors

| Exit     | Meaning                                                                                                | What to do                                 |
| -------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| 0        | Success                                                                                                | Continue                                   |
| 2        | Bad command or build                                                                                   | Fix the input and run the command again    |
| 3        | Rosebud rejected the request; read `error.code`                                                        | Fix the cause below, then retry            |
| 4        | The outcome is unknown, for example after a lost response (`outcome` `not_sent`: nothing was released) | Follow step 3 or step 6 above; don't guess |
| 130, 143 | Stopped by SIGINT or SIGTERM (`interrupted`)                                                           | Run the command again                      |

| `error.code`                                                      | Fix                                                                                                                                          |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `missing_index`                                                   | Put `index.html` at the top of the build folder, not in a subfolder                                                                          |
| `state_in_build`                                                  | Publish the build folder, not the project root (see step 1)                                                                                  |
| `unsafe_path`                                                     | Remove or rename the hidden or oddly named file `error.message` names (see the name rules in step 1), or publish a copy in `./dist`          |
| `excluded_file`                                                   | Remove the credentials, `node_modules` or `.env` file the error names                                                                        |
| `duplicate_path`                                                  | Two names in the folder are the same name in Unicode NFC. Keep one                                                                           |
| `file_changed`                                                    | Exit 2. A media file changed while it was uploading, for example during a build. Nothing was sent. Run the command again once it's finished  |
| `invalid_text`                                                    | The text file isn't UTF-8, has a NUL byte or holds a private key. Fix it, or move real binary media into `assets/`                           |
| `media_path`, `noncanonical_path`                                 | Move media into `assets/` and rename it as `error.message` says                                                                              |
| `unsupported_file`, `invalid_media`                               | Correct the named file; keep license notices as supported UTF-8 text                                                                         |
| `compressed_limit`, `expanded_limit`, `entry_limit`, `file_limit` | Shrink or remove assets until the build fits the limits in step 1                                                                            |
| `release_upload_limit`                                            | Publish or update with part of the new media, then again with the rest (see step 1)                                                          |
| `game_expired`                                                    | See "If the claim deadline passes"                                                                                                           |
| `login_pending`                                                   | Ask the person to approve the `rosebud login` link, or run `rosebud logout` to publish with a claim link                                     |
| `login_inactive`                                                  | Run `rosebud login` again, or `rosebud logout` to publish with a claim link                                                                  |
| `key_expired`                                                     | The login went 90 days without use. Run `rosebud login` again and ask the person to approve it                                               |
| `insufficient_scope`                                              | The login lacks `required_scope`. Run `rosebud logout`, then `rosebud login`                                                                 |
| `connection_pending`, `connection_expired`, `connection_revoked`  | Run `rosebud connect` and ask the person to approve                                                                                          |
| `version_conflict`                                                | Reconcile as described in "When Rosebud changed the game"                                                                                    |
| `pull_conflicts`, `directory_mismatch`                            | Exit 2. Follow `next_action`; see "When Rosebud changed the game"                                                                            |
| `folder_changed`                                                  | Exit 2. A file pull would replace or remove changed while it downloaded, so pull left the folder as it was. Run it again                     |
| `download_corrupt`                                                | Exit 4. A download didn't match its checksum, or its size when Rosebud has none. Pull changed nothing in the folder; run it again            |
| `state_locked`                                                    | Another `rosebud` command is using this state file. Wait for it to finish, then run yours again                                              |
| `pending_operation`                                               | An earlier update's outcome is unknown. Rerun its identical command, or run `rosebud status`, reconcile, then pass `--expected-version`      |
| `plan_required`                                                   | See "If pull fails with plan_required"                                                                                                       |
| `sync_unavailable`                                                | This Rosebud server can't read files back (`pull`) yet. Nothing was changed; try again later. Uploads fall back to one ZIP of at most 10 MiB |
| `unsupported_project`                                             | Rosebud can't read this game's files back. Tell the person                                                                                   |
| `busy`                                                            | Run the same command again after `retry_after_seconds`; nothing was changed                                                                  |
| `upload_retry`                                                    | Rosebud is still checking the game's existing files. Run the same command again                                                              |
| `project_busy`                                                    | Rosebud is still generating changes to this game; wait, then retry                                                                           |

Bundlers are the usual cause of media errors. Vite adds mixed-case hashes to imported assets (`assets/logo-BdF3x9.png`) and copies its `public/` folder to the top of the build, outside `assets/`. For Vite, keep media file names lowercase, move `public/` media under `public/assets/`, and set `build.rollupOptions.output.assetFileNames` to `'assets/[name].[ext]'`.
