# Rosebud for developers URL: /docs/get-started > Host browser games for free and make game assets with your Rosebud credits, from a terminal or a coding agent. The Rosebud CLI does two things: * **Free game hosting.** Publish a browser game's build folder and get a link anyone can play. Updates go to the same link. * **Game assets**. Make sprites, 2D art, skyboxes, 3D models, video clips, sound effects, music and speech with your Rosebud credits, at the same prices as the website. Every command prints JSON, so coding agents like Claude Code, Codex and Cursor can run the whole flow and read the results. - [Quickstart](/docs/get-started/quickstart.md): Install the CLI and publish a game in a few minutes. - [Use a coding agent](/docs/get-started/coding-agents.md): Give your agent one prompt, or point it at the Markdown docs. - [Make assets](/docs/guides/make-assets.md): Log in once, check the price, and save files into your game. - [Models](/docs/models.md): Every model, its inputs, price and license. ## What's in these docs | Section | What's there | | ------------------------------------------- | ---------------------------------------------------------- | | [Get started](/docs/get-started/quickstart.md) | Install, first publish, and how sign-in works. | | [Guides](/docs/guides/publish-a-game.md) | Step-by-step tasks: publishing, claiming, updates, assets. | | [CLI](/docs/cli.md) | One page per command, with every flag, output and error. | | [HTTP API](/docs/api.md) | The endpoints the CLI calls, for building your own client. | | [Models](/docs/models.md) | The asset models, generated from the live model list. | Every page is also available as Markdown: add `.md` to its URL. The whole site is indexed for agents at [`/docs/llms.txt`](/docs/llms.txt). # Quickstart URL: /docs/get-started/quickstart > Install the Rosebud CLI and publish your first game. You need Node.js 22 or later. ### 1. Install the CLI ```sh npm install --global @rosebudai/cli ``` To run it without installing, use `npx @rosebudai/cli` in place of `rosebud`, for example `npx @rosebudai/cli publish --directory ./dist`. ### 2. Publish your build folder Build your game, then publish the build folder from your project's root: ```sh rosebud publish --directory ./dist --title 'Moon Garden' \ --description 'Collect five glowing seeds.' ``` Already have a ZIP? Use `--zip ./game.zip` instead of `--directory`. No build step? Copy `index.html` and everything it loads into a folder such as `./dist` and publish that, not the project root. ### 3. Play it Open the `play_url` from the result and play the game. A successful upload means the files were accepted, not that the game works. ### 4. Claim it within an hour Open the `claim_url`, sign in and select **Claim game**. Unclaimed games are deleted after one hour. If you ran [`rosebud login`](/docs/cli/login.md) first, the game is already in your account and there's nothing to claim. Planning to ship updates? Run `rosebud connect` instead and open its `approval_url`. Approving it claims the game and lets the CLI update it, in one step. The CLI saves the game's details in `.rosebud/project.json`, so later commands know which game to update. Add `.rosebud/` to `.gitignore`. ## Next steps - [Publish updates](/docs/guides/publish-updates.md): Connect the game once, then ship new builds to the same link. - [Make assets](/docs/guides/make-assets.md): Art, 3D models and sound, paid with your credits. # Use a coding agent URL: /docs/get-started/coding-agents > Let Claude Code, Codex, Cursor or Gemini CLI publish your game and make its assets. The CLI is built for agents: every command prints one JSON object, errors say what to fix, and an interrupted `update`, `pull` or `assets create` is safe to run again (an interrupted `publish` is not). ## Give your agent a prompt Paste this into your agent: ```text Publish this game with Rosebud. Follow the instructions at https://rosebud.ai/developer-publishing/AGENTS.md. ``` To make art and sound as well: ```text Make the art and sound this game needs with Rosebud. Follow the instructions at https://rosebud.ai/developer-assets/AGENTS.md. Show me the price before you make anything over 500 credits, and save the files into the project's assets folder. ``` The agent installs the CLI, runs the commands and gives you any link you need to open, such as a claim or approval link. ## Agent instructions These files have the same steps as the guides, written as instructions for an agent: | File | Covers | | -------------------------------------------------------------------- | ----------------------------------------------- | | [`/developer-publishing/AGENTS.md`](/developer-publishing/AGENTS.md) | Publishing, claiming and updating a game. | | [`/developer-assets/AGENTS.md`](/developer-assets/AGENTS.md) | Signing in, choosing a model and making assets. | ## Markdown for every page * Add `.md` to any docs URL for its Markdown, for example [`/docs/cli/publish.md`](/docs/cli/publish.md). * [`/docs/llms.txt`](/docs/llms.txt) lists every page with a one-line description. * [`/docs/llms-full.txt`](/docs/llms-full.txt) has every page in one file. Each page also has **Copy Markdown** and **Open** buttons for pasting it into ChatGPT, Claude or another tool. ## What agents can and can't do Agents never see your password, and every kind of access needs you to approve a link. See [Sign-in and access](/docs/get-started/access.md) for what each approval allows. # Sign-in and access URL: /docs/get-started/access > Claim links, game connections and agent logins, and what each one allows. The CLI never asks for your password or an API key. Instead, it prints a private link, and you open it, sign in on rosebud.ai and approve. | Link | Comes from | Lets the CLI | Expires | | -------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | | Claim link (`claim_url`) | `rosebud publish`, without a login | Nothing. It moves the game into your account. | One hour after upload | | Game connection (`approval_url`) | `rosebud connect` | Update one game: its files, title, description and cover. | Link: 30 minutes. Access: 90 days. | | Agent login (`approval_url`) | `rosebud login` | Make and download assets with your credits, and publish new games into your account. | Link: 30 minutes. Access: 90 days after its last use. | Keep all three links private. Anyone who has one can use it. ## Game connections A connection covers a single game. It can't reach your other games, your account or billing, or run AI generation. Revoke it in the game's **Project Settings → Manage connected agents** (not the Connected agents page), or run [`rosebud disconnect`](/docs/cli/disconnect.md). ## Agent logins A login can make assets, list and download your assets, and publish new games into your account. It can't change billing or manage your account. Revoke it on your account's [Connected agents](/developers/keys) page, or run [`rosebud logout`](/docs/cli/logout.md). An expired login isn't renewed: approve a new one with `rosebud login`. Logging out, or a login that expires, doesn't disconnect the games it published. Each of those has its own game connection, which lasts 90 days. ## Where credentials are stored The CLI keeps credentials in `~/.config/rosebud/credentials` with private file permissions, separate from the project. Set `ROSEBUD_CREDENTIALS_DIR` to use another folder. Game details (not secrets) go in `.rosebud/project.json` in your project. # Publish a game URL: /docs/guides/publish-a-game > Put a browser game online for free and get a link anyone can play. You don't need an account to publish. To keep a game, sign in and [claim it](/docs/guides/claim-your-game.md) within an hour. Or run [`rosebud login`](/docs/cli/login.md) first, so new games go straight into your account. No game yet? Clone [rosebudai/rosebud-cli](https://github.com/rosebudai/rosebud-cli) and run `rosebud publish --directory ./examples/signal-garden`. ## Publish the build folder Build your game, then run this from your project's root: ```sh rosebud publish --directory ./dist --title 'Moon Garden' \ --description 'Collect five glowing seeds.' ``` * The title and description are optional. They appear on the game's play page. * Add `--thumbnail ./cover.png` for a cover (see [Game details](#game-details)). * Already have a ZIP? Use `--zip ./game.zip` instead of `--directory`. Don't publish the project root. The CLI keeps its state in `.rosebud/` there, and hidden files such as `.gitignore` can't be uploaded. With no build step, copy the files your game needs into `./dist` and publish that. Open the `play_url` and play the game. A successful upload means the files were accepted, not that the game works. If you're signed in with a login that's still waiting for approval, `publish` fails with `login_pending`. Approve the login, or run `rosebud logout` to publish with a claim link instead. ## What you can upload * `index.html` at the top level of the build folder. * Text files, anywhere in the build: HTML, JavaScript, CSS and JSON, Markdown notes such as `AGENTS.md`, 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. * UTF-8 text notices: `.txt` files (including `.TXT`) and extensionless `LICENSE`, `LICENCE`, `NOTICE`, `COPYING`, `COPYRIGHT` and `AUTHORS`. They keep their original names; the media naming rules don't apply to them. Don't remove required notices to make an upload pass. * Media inside `assets/`. Names are lowercase letters, numbers, underscores and single hyphens; they start and end with a letter or number, and use dots only for the extension. Media elsewhere is refused with `media_path`, and an empty media file with `file_limit`. * Images: PNG, JPEG, WebP and SVG * Audio: MP3, WAV, OGG and OGA * Fonts: WOFF, WOFF2, TTF and OTF * WASM, and GLB and glTF models with their `.bin` buffers Outside `assets/`, `.svg` and `.gltf` files are text. Names are compared in Unicode NFC, so two names that differ only in how an accented letter is stored are one name; keep one, or the upload is refused with `duplicate_path`. ### Limits | Limit | Size | | ---------------------------------- | ---------------------------------------------------------------------- | | Text files | One ZIP: 10 MiB zipped, 50 MiB unzipped, 500 entries | | One media file | 19 MiB (media uploads file by file) | | Whole game | 2,000 files and 1 GiB | | New media in one publish or update | 128 MiB (`release_upload_limit`) | | Image size | 10,000 pixels a side | | `--zip` archive | All of it, media included: 10 MiB zipped, 50 MiB unzipped, 500 entries | Files Rosebud already has, with the same path, size and MD5, aren't uploaded again and don't count toward the 128 MiB. Over that, publish with part of the media, then `update` with the rest. `--zip` sends your archive as it is, so use `--directory` for a game with more media than the ZIP limits allow. CLI 0.1.0 sends the whole build as one ZIP under the text-file limits; update to 0.2.0 for bigger games. Large games can take minutes to upload, because each media file goes up on its own and Rosebud may first check the files it already has. Rosebud serves your files as they are and doesn't run a build. `.DS_Store`, `Thumbs.db` and `desktop.ini` are skipped, never uploaded and never an error. Other hidden files, symbolic links, dependency folders and unsupported file types are rejected. > Everything you upload is public. Keep credentials and `.env` files out of the build. Rosebud refuses names ending in `.env`, `credentials`, `secrets`, `credentials.json`, `service-account.json`, `service_account.json`, `node_modules` and anything containing `firebase-adminsdk` (`excluded_file`), and any file that holds a private key. Hosted games are unlisted: anyone with the link can play, but they don't appear in Rosebud's game listings. ## Game details All of these are optional, for both `publish` and `update`: | Option | Details | | --------------- | ------------------------------------------------------------------------ | | `--title` | Up to 255 characters. Changing it later keeps the same play link. | | `--description` | Up to 4,000 characters. | | `--thumbnail` | A PNG or JPEG gameplay screenshot, at most 2 MiB and 4096 pixels a side. | Agents can also pass `--agent-client` (`claude-code`, `codex`, `cursor`, `gemini-cli` or `other`) to say which tool published the game. # Claim your game URL: /docs/guides/claim-your-game > Keep a game you published without an account, before its one-hour deadline. A new upload is playable right away, but it's temporary until someone claims it. The result's `claim_expires_at` is the deadline, one hour after upload. To claim it, open the `claim_url`, sign in and select **Claim game**. * **Claimed in time:** the game moves into your Rosebud account, keeps its link and opens in the Rosebud editor. It no longer expires. * **Not claimed:** at the deadline the game, its files and its links stop working, and the game is permanently deleted. There's no late claim. Keep the claim link private. Anyone who has it can claim the game. > Signed in with [`rosebud login`](/docs/cli/login.md)? Then `publish` puts the game straight into your account. The > result has `claimed: true` and an `editor_url`, and there's no claim link. ## If a game expires Publish the same build again as a new game. Use a new state file so the CLI doesn't confuse it with the deleted one: ```sh rosebud publish --directory ./dist --state .rosebud/new-project.json \ --title 'Moon Garden' ``` The new game gets a new link. Pass the same `--state` to later commands for it. # Publish updates URL: /docs/guides/publish-updates > Connect a game once, then ship new builds to the same link. ## Connect the game ```sh rosebud connect ``` This prints a private `approval_url`. Open it, sign in and select **Allow updates**. If the game isn't claimed yet, the button reads **Claim game and allow updates**, and approving also claims it. The link expires after 30 minutes; run `rosebud connect` again for a new one. Published with an active [`rosebud login`](/docs/cli/login.md)? The connection is already saved, so skip this step. ## Ship a new build ```sh rosebud status rosebud update --directory ./dist ``` * Rebuild first, or copy your files into `./dist` again if you have no build step. * [`status`](/docs/cli/status.md) shows whether access is active and which version of the game is live. * Titles, descriptions and covers you don't pass to `update` stay as they are. * `update` makes the game exactly the folder you give it. A file the game has that the folder lacks is removed from the game, and files Rosebud already has aren't uploaded again. * If an update is interrupted, run the same command again. It won't publish twice. ## If the game changed on Rosebud Edits in the Rosebud editor, changes by Rosie and updates from another agent make your saved version stale. `update` then stops with `version_conflict` (exit 3) instead of overwriting, and changes nothing. Its `changed_paths` says what changed: | `changed_paths` | Meaning | | --------------- | ------------------------------------------------------------------------------------------------- | | A list of paths | Rosebud changed, added or removed these files since your last sync (up to 4,000 paths). | | `[]` | No file changed. Only the title, description, cover or published copy did. | | `null` | Rosebud can't tell which files changed, for example for a version you learned only from `status`. | | Missing | This Rosebud server doesn't report changed files. | For `[]`, run `rosebud status` and pass its `content_version` as `--expected-version`. Bring those changes in with [`rosebud pull`](/docs/cli/pull.md), then update: ```sh rosebud pull --directory ./dist rosebud update --directory ./dist ``` `pull` keeps your own edits and lists any file changed on both sides as a conflict to merge; `rosebud pull --force` takes Rosebud's version of each conflicted file instead. Files Rosebud has that your folder lacks are listed under `missing_locally`, and the next update removes them from the game unless you restore them. If your game has a build step, pull into a new, empty folder such as `./rosebud-files`, copy the changes into your source and rebuild, then update with `--expected-version `. If you can't pull (it needs the owner's plan to include code download), ask what changed in the editor and make the same changes locally, then accept the current version explicitly: ```sh rosebud update --directory ./dist --expected-version ``` `update` never merges or overwrites on its own. ## On another computer ```sh rosebud connect --project ``` This works for a claimed game. The project ID is in `.rosebud/project.json`, or in the editor's address, `https://rosebud.ai/edit/`. Approve the new link, then run `rosebud status` before your first update. ## Revoke access Access lasts 90 days and covers only this game. Revoke it any time in the editor under **Project Settings → Manage connected agents**, or run: ```sh rosebud disconnect ``` The game stays online. # Edit a game made in Rosebud URL: /docs/guides/edit-a-rosebud-game > Bring a game made in the Rosebud editor into a folder, change it locally and publish it back. Use this to change a game someone built in the Rosebud editor, with your own tools or a coding agent. Pulling needs Rosebud Pro or higher on the owner's account, for code download; see [Pricing](/pricing). Without it, `pull` fails with `plan_required`, while `update` still works: tell your agent what you changed in Rosebud before it updates. ### 1. Connect to the game Find the project ID in the editor's address, `https://rosebud.ai/edit/`, then run: ```sh rosebud connect --project ``` Open the `approval_url` it prints, sign in as the game's owner and approve. `rosebud status` reports `active` once you have. ### 2. Pull its files ```sh rosebud pull --directory ./game ``` This writes the game's current files, text and media, including edits made in Rosebud, into `./game`. Use a folder that holds only the game: `update` refuses hidden files such as `.git`. On Windows, a name Windows can't keep (one ending in a dot or space, or a device name such as `con.js`) is skipped. Games made with Rosie include `AGENTS.md` and other notes. Read them before you change anything. ### 3. Edit and publish ```sh rosebud update --directory ./game ``` The game keeps its link. Files Rosebud already has aren't uploaded again. Keep new media in `assets/` with [lowercase names](/docs/guides/publish-a-game.md#what-you-can-upload). Media the editor accepts but an update can't upload, such as MP4, GIF, WebM, M4A, FBX or OBJ, is kept only if you leave the file unchanged at the same path. Changing or renaming one is refused with `unsupported_file`: do that in the Rosebud editor, then pull again. If someone keeps editing in Rosebud while you work, run `rosebud pull --directory ./game` again before each update. It brings in their changes and keeps yours. See [`rosebud pull`](/docs/cli/pull.md) for conflicts. # Make assets URL: /docs/guides/make-assets > Make sprites, 2D art, skyboxes, 3D models, video and sound with your Rosebud credits. Assets are paid for with your Rosebud credits, at the same prices as the website. Everything you make also shows up in [My assets](/assets). Need more credits? See [Pricing](/pricing). ### 1. Log in once ```sh rosebud whoami ``` If it reports `"status": "active"`, skip ahead. If it reports another status, or fails with `login_required`, run: ```sh rosebud login ``` Open the `approval_url` it prints, sign in and select **Allow**. Then run `rosebud whoami` again. It shows your credit balance once the login is active. Agents should add `--agent-client` (for example `--agent-client claude-code`) so you can tell their logins apart when you approve them. ### 2. Choose a model ```sh rosebud assets models --category image ``` Each model lists its inputs, price and license. Categories are `image`, `skybox`, `model_3d`, `video`, `sound_effect`, `music` and `speech`. Leave out `--category` to see every model, or browse the same list on [Models](/docs/models.md). ### 3. Check the price ```sh rosebud assets quote --model flux-2-flash --prompt 'green slime monster, side view' \ --input asset_type=sprite ``` Quotes are free and check your inputs. `--prompt` fills the model's `prompt` input, and `--input name=value` sets any other input it lists. Add-ons, such as a transparent background for a sprite, are included in the price. ### 4. Make the asset ```sh rosebud assets create --model flux-2-flash --prompt 'green slime monster, side view' \ --input asset_type=sprite \ --max-credits 300 --out ./assets/slime.png ``` * `--max-credits` caps the price. `create` refuses a higher quote before anything is charged. * `create` waits for the file (up to 10 minutes) and saves it to `--out`. It never replaces an existing file unless you pass `--force`. * With `--no-wait` it returns the job at once. Check it with `rosebud assets status `, then save the file with `rosebud assets download --out `. * Credits are charged when a job starts and returned if generation fails. ### 5. Use it in the game Save files where the game loads them, then load the game and check each file appears or plays. If you'll publish with Rosebud's free hosting, keep media inside `assets/` with lowercase names. See [Asset formats and tips](/docs/guides/asset-results.md) for sizes and quirks. ## Reuse an asset you already made Everything you make, from the CLI or the website, stays in My assets. Search it and download a file instead of paying again: ```sh rosebud assets list --query 'slime' rosebud assets download --out ./assets/slime.png ``` `list` shows the 25 newest matches. Narrow it with `--query` or `--category` (`image`, `sprite`, `skybox`, `model_3d`, `audio` or `file`). `sprite` means animated sprite sheets made on the website; images made with `asset_type=sprite` are `image`. `audio` covers sound effects and music. ## Rules for agents * Show the person the price before anything expensive, and pick the cheapest model that fits. * Make one asset per command. Make variations by changing the prompt or inputs. * Run a few commands at a time, not dozens. Quotes and job starts share a limit of 30 per minute per account. The CLI waits out a throttle for up to a minute before it reports `throttled`. * Keep the login while you work. Run `rosebud logout` only to switch accounts or when the person asks. * If a command exits with code 4, run the identical command again. It resumes the same job and won't pay twice. * Don't retry when the person is out of credits. Tell them instead. * When you're done, tell the person what you made and what it cost. # Asset formats and tips URL: /docs/guides/asset-results > Sizes, formats and quirks of each kind of asset, and how to use them in a game. ## Images * Flux 2 Flash backgrounds and textures are 1024×1024, with no size or aspect-ratio input. Crop or scale them in the game. * Transparent types (`sprite`, `icon`, `character_portrait` and the like) are cropped to their content, so their sizes vary. * PNGs run 1–2 MB each. Add `--input output_format=webp` when the game will be hosted: smaller files load faster, and a hosted game has [size limits](/docs/guides/publish-a-game.md#limits). * `texture_tile` images are close to seamless but not exact. Check the edges before tiling them across a large surface. * To keep a character the same across poses or expressions, pass its image to a model that takes `image` (such as `nano-banana-pro` or `gpt-image-2-5`) and describe only the change. `qwen-multiple-angles` shows the same subject from another side. With Flux 2 Flash, which takes no image, repeat the same description and the same `--input seed=`, changing only the pose. * `remove-background`, `crisp-upscale` and `vectorize` take an existing image. `recraft-4-1-svg` and `vectorize` return SVG; `ideogram-tiling` returns a seamless texture. * There's no sprite animation model yet. A sprite sheet asked of an image model often comes back in a different grid or frame count than requested, so slice it by content rather than by a fixed grid. Run `rosebud assets models` for the current models and what each one accepts. ## Skyboxes `rosebud-skybox` returns a 2:1 equirectangular WebP. In three.js, load it with `TextureLoader`, set its `mapping` to `THREE.EquirectangularReflectionMapping`, and assign it to both `scene.background` and `scene.environment`. ## 3D models `rosie-3d` makes GLB files about 1 unit along their longest side, Y up, facing +Z, with the base at y = 0. * They use the `KHR_mesh_quantization` and `EXT_texture_webp` extensions, which three.js loads. * Humanoid characters usually come back rigged, with a Mixamo-style skeleton and about 80 animation clips such as `Idle`, `Walk`, `Run` and `Death01`. Read the clip names from the file. * Metallic surfaces render nearly black without an environment map. A skybox set as the scene's environment lights them. Other 3D models (`meshy-7-1`, `tripo-p2`, `rodin-2-5`) make GLBs at their own scale and facing, so measure the bounding box and scale each one in the game. They aren't rigged; `meshy-rigging` adds a humanoid skeleton to a character GLB. ## Videos MP4 clips up to 10 seconds, for cutscenes, intros and backgrounds. An `image` input becomes the first frame. Clips cost far more than images, and the price depends on length, so quote first and keep them short. ## Speech An MP3 of the prompt read aloud, priced by its length. Name an ElevenLabs voice with `--input voice=`. ## Sound effects 0.5–5 second MP3s. Ask for one sound per clip, since a second event in the same prompt is usually dropped. Loudness varies between clips, so set each one's volume in the game. ## Music At most 30 seconds, and it may fade out at the end even when the prompt asks for a loop. Trim the fade before looping it. > Give every game with sound a mute button and a volume control, and start music quieter than effects. People often > play with others around, on a call or in class. # Troubleshooting URL: /docs/guides/troubleshooting > Common errors, what to do about each, and how to recover from interrupted commands. Commands print JSON (except `--help` and `--version`): results on stdout, errors on stderr. Errors include a `code`, a `message` that says what to fix and often a `next_action`. When Rosebud rejects a specific file, `filename` names it. The [CLI overview](/docs/cli.md#exit-codes) lists the exit codes. ## Unknown results (exit 4) * **`publish`:** the game may already exist. Don't publish again right away; a new publish creates a second game. * **`update`:** run the same command again without changing your files. It won't publish twice, and it sends the media the way the first attempt did. If the folder changed meanwhile, it refuses with `pending_operation`. * **`pull`:** run it again. It finishes the work. * **`assets create`:** run the identical command again. It resumes the same job and won't pay twice. With `outcome` `not_sent`, nothing was released. When Rosebud throttles a request, the CLI waits as long as Rosebud asks and sends it again, for up to a minute. It never sends a publish or update again on its own. ## Common errors ### Publishing | Error | Fix | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `state_in_build`, or `unsafe_path` for a hidden file | You published the project root. Publish the build folder, or a copy of the game in `./dist`. | | `missing_index` | Put `index.html` at the top level of the folder you publish. | | `media_path`, `noncanonical_path` | Usually bundler output. Vite adds mixed-case hashes to asset names and copies `public/` to the build root. Move `public/` media under `public/assets/` and set `build.rollupOptions.output.assetFileNames` to `'assets/[name].[ext]'`. | | `compressed_limit`, `expanded_limit`, `entry_limit`, `file_limit` | The build or a file is too big, or a media file is empty. `limit` gives the bound. See [Limits](/docs/guides/publish-a-game.md#limits). | | `release_upload_limit` | One publish or update adds more than 128 MiB of new media. Send part of it, then `update` with the rest. | | `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. | | `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/`. | | `unsupported_file`, `invalid_media` | Correct the named file. For editor-only media such as MP4, leave it unchanged at its path, or change it in the Rosebud editor. | | `file_changed` | A media file changed while uploading, for example during a build. Nothing was sent. Run the command again once the build has finished. | | `project_exists` | The state file already holds a game. Use `rosebud update`, or pass a new `--state` to publish another game. | | `login_pending` | Your login still waits for approval. Approve it, or run `rosebud logout` to publish with a claim link. | | `game_expired` | The claim deadline passed. [Publish again as a new game](/docs/guides/claim-your-game.md#if-a-game-expires). | ### Updating | Error | Fix | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `connection_required`, `connection_pending` | Run `rosebud connect` and approve its link, then `rosebud status`. | | `invalid_connection`, `connection_expired`, `connection_revoked` | Access expired or was revoked. Run `rosebud connect` again. | | `version_conflict` | The game changed on Rosebud. See [Publish updates](/docs/guides/publish-updates.md#if-the-game-changed-on-rosebud). | | `pull_conflicts` | Merge the files the last pull listed, then pull again or pass `--expected-version`. See [`rosebud pull`](/docs/cli/pull.md#conflicts). | | `directory_mismatch` | You last pulled into another folder. Pull into this folder first, or pass `--expected-version` to release it anyway. | | `pending_operation` | An earlier update's outcome is unknown. Run it again unchanged, or run `rosebud status` and pass `--expected-version`. | | `plan_required` | `pull` needs Rosebud Pro or higher on the owner's account. `update` still works; ask what changed in Rosebud first. | | `folder_changed`, `download_corrupt` | A file changed while `pull` downloaded, or a download arrived damaged. `pull` left the folder as it was. Run it again. | | `sync_unavailable` | This Rosebud server can't read files back yet. Nothing changed; try again later. | | `unsupported_project` | Rosebud can't read this game's files back. Tell the game's owner. | | `upload_retry` | Rosebud is still checking the game's existing files. Run the same command again. | | `project_busy` | Rosebud is generating in the game. Wait for it to finish, then run the command again. | | `busy` | Rosebud is busy and changed nothing. Wait `retry_after_seconds`, then run the command again. A first `publish` refused as busy created nothing. | ### Assets | Error | Fix | | ---------------------- | ------------------------------------------------------------------------------------------------- | | `login_required` | No login on this computer. Run `rosebud login`. | | `invalid_key` | The login is pending or was disconnected. Run `rosebud whoami`, then `rosebud login`. | | `key_expired` | The login wasn't used for 90 days. Run `rosebud login`. | | `insufficient_scope` | The login lacks the permission in `required_scope`. Run `rosebud logout`, then `rosebud login`. | | `insufficient_credits` | You need more credits. Buy credits or upgrade on [Pricing](/pricing). Don't retry. | | `max_credits` | The quote is above `--max-credits`. Nothing was charged. Raise the cap or choose a cheaper model. | | `file_exists` | `--out` already exists. Choose another path, or pass `--force` to replace it. | | `job_unfinished` | The wait ran out. Run the identical command again to keep waiting for the same job. | | `throttled` | Too many requests at once. Wait `retry_after_seconds`, then run the identical command. | The [HTTP API errors](/docs/api/errors.md) page lists every code Rosebud returns. ## Moved the project folder? The saved game connection is tied to the state file's path. After you move or rename the project folder, commands fail with `connection_required`. Run `rosebud connect` again. ## Lock files The CLI locks its state file while a command runs, so run commands against one state file one at a time. If another command holds the lock, the CLI stops with `state_locked`. A command stopped with Ctrl+C releases its lock, and a lock left by a process that has stopped is taken over automatically (CLI 0.2.0 and later). On 0.1.0, make sure the crashed command has stopped, then delete the `.lock` file next to the state file. # Get help URL: /docs/guides/get-help > Report a bug, ask a question or report a security problem. * **Bugs and questions:** open an issue on [rosebudai/rosebud-cli](https://github.com/rosebudai/rosebud-cli/issues). Include the command you ran and the JSON error, but never a claim link, approval link or credentials. * **Security problems:** report them privately through the repository's [Security tab](https://github.com/rosebudai/rosebud-cli/security), not in a public issue. * **Changes:** see the [changelog](/docs/cli/changelog.md). ## Source and releases The CLI is open source under Apache-2.0. Each [npm release](https://www.npmjs.com/package/@rosebudai/cli) is built by GitHub Actions and published with npm provenance, which links it to the source it was built from. ## Coming soon We're working on an in-game SDK for gameplay events and error reports, and dashboards for sessions and returning players. None of these are available yet, and hosting doesn't need an SDK in your game. # CLI overview URL: /docs/cli > Install the Rosebud CLI, and how its output, exit codes, state and credentials work. The Rosebud CLI publishes browser games and makes game assets. It's open source under Apache-2.0: [rosebudai/rosebud-cli](https://github.com/rosebudai/rosebud-cli). ## Install You need Node.js 22 or later. It works on macOS, Linux and Windows. ```sh npm install --global @rosebudai/cli rosebud --version ``` Or run any command without installing: `npx @rosebudai/cli `. `pull`, `login` and the `assets` commands need 0.2.0 or later; if one is reported as an unknown command, run the install again to update. ## Commands | Command | What it does | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | [`rosebud publish`](/docs/cli/publish.md) | Creates a new game from a build folder or ZIP. | | [`rosebud connect`](/docs/cli/connect.md) | Prints a private link that lets you approve updates from this CLI. | | [`rosebud status`](/docs/cli/status.md) | Shows whether access is pending, active, revoked or expired. | | [`rosebud update`](/docs/cli/update.md) | Replaces the game's files and publishes them to the same link. | | [`rosebud disconnect`](/docs/cli/disconnect.md) | Revokes this CLI's access. The game stays online. | | [`rosebud pull`](/docs/cli/pull.md) | Brings the game's current files, including Rosebud edits, into a folder. | | [`rosebud login`](/docs/cli/login.md) | Asks you to approve this CLI or agent to make assets with your credits and publish into your account. | | [`rosebud whoami`](/docs/cli/whoami.md) | Shows the login's status and your credit balance. | | [`rosebud logout`](/docs/cli/logout.md) | Revokes the login and removes it from this computer. | | [`rosebud assets models`](/docs/cli/assets/models.md) | Lists models with their inputs, prices and licenses. | | [`rosebud assets quote`](/docs/cli/assets/quote.md) | Checks inputs and prices an asset, free. | | [`rosebud assets create`](/docs/cli/assets/create.md) | Makes an asset, waits for it and saves the file. | | [`rosebud assets status`](/docs/cli/assets/status.md) | Shows a job's progress and, when done, its asset. | | [`rosebud assets list`](/docs/cli/assets/list.md) | Lists your assets, newest first. | | [`rosebud assets download`](/docs/cli/assets/download.md) | Saves an existing asset's file. | ## Global options | Option | Default | Details | | ------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--state ` | `.rosebud/project.json` | Where the game's details are saved. Use one per game. | | `--timeout-ms ` | `120000` | How long to wait for Rosebud. For `assets create` it bounds the whole wait, default `600000`. Each file upload gets one extra second per 32 KiB on top. | | `--help` | | Lists commands and options. | | `--version` | | Prints the installed version. | ## Output Every command except `--help` and `--version` prints one JSON object: results on stdout, errors on stderr. Many results include a `next_action` that says what to do next. Errors look like this: ```json { "error": { "code": "media_path", "message": "Move assets/Hero.PNG to assets/hero.png and update references.", "kind": "api", "outcome": "rejected", "status": 400, "filename": "assets/Hero.PNG" } } ``` `outcome` is `not_sent`, `rejected` or `unknown`; with `not_sent`, nothing was released. `limit` is a number when Rosebud reports one. Asset errors include the `job_id` or `asset_id` once one is known. A request that Rosebud throttles (HTTP 429) waits out its `Retry-After` and is sent again, for up to a minute in all. A longer wait fails with `throttled` and `retry_after_seconds`. A publish or update request is never sent again on its own. ## Exit codes | Exit | Meaning | | -------- | --------------------------------------------------------------------------------------------------- | | 0 | Success. Check `status` or `whoami` to see whether approval is still pending. | | 2 | Local input or usage error. Fix the command or build. | | 3 | Rosebud rejected the request. Read `error.code` before retrying. | | 4 | The outcome is unknown. See [Troubleshooting](/docs/guides/troubleshooting.md#unknown-results-exit-4). | | 130, 143 | Stopped by Ctrl+C or SIGTERM (`interrupted`). The state lock is released. | ## State and credentials * `.rosebud/project.json` holds the game's ID, play link and last accepted version, but no secrets. Keep `.rosebud/` out of Git and outside your build folder. * Credentials (game connections and the login) are kept in `~/.config/rosebud/credentials` with private file permissions. Set `ROSEBUD_CREDENTIALS_DIR` to use another folder. * The CLI locks the state file while it runs. Run commands against one state file one at a time. A lock left by a process that no longer runs is taken over by the next command. # rosebud publish URL: /docs/cli/publish > Create a new game from a build folder or ZIP and get a play link. ```sh rosebud publish --directory [options] rosebud publish --zip [options] ``` Each `publish` creates a new game and saves its details to the state file. To change a game you already published, use [`rosebud update`](/docs/cli/update.md). ## Options | Option | Details | | ------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `--directory ` | The build folder to upload. It needs `index.html` at the top level. | | `--zip ` | A ZIP of the build, instead of `--directory`. | | `--title ` | Up to 255 characters. `--name` is accepted as an alias. | | `--description ` | Up to 4,000 characters. | | `--thumbnail ` | A PNG or JPEG cover, at most 2 MiB and 4096 pixels a side. | | `--agent-client ` | `claude-code`, `codex`, `cursor`, `gemini-cli`, `other` or `unknown`. | | `--context ` | A JSON file with optional details about how the game was made. See [Import a game](/docs/api/hosting/import.md#context). | | `--state ` | Where to save the game's details. Default `.rosebud/project.json`. | Use exactly one of `--directory` and `--zip`. See [what you can upload](/docs/guides/publish-a-game.md#what-you-can-upload). ## Example ```sh rosebud publish --directory ./dist --title 'Moon Garden' \ --description 'Collect five glowing seeds.' ``` Without a login, the result has a private claim link: ```json { "project_id": "6f1d2c8e-...", "play_url": "https://rosebud.ai/play/moon-garden", "claim_url": "https://rosebud.ai/claim#...", "claim_expires_at": "2026-10-27T19:04:11Z", "content_version": "9f2c41e0b7...", "state_file": ".rosebud/project.json", "next_action": "Claim by 2026-10-27T19:04:11Z to keep this game online for free. ..." } ``` With an active [`rosebud login`](/docs/cli/login.md), the game goes straight into the account. The result has `claimed: true`, the `owner` and an `editor_url` instead of a claim link, and `update` works at once. If Rosebud couldn't add the game to the account, the result has the claim fields instead. ## Notes * Unclaimed games are deleted one hour after upload. See [Claim your game](/docs/guides/claim-your-game.md). * If the result is unknown (exit 4), the game may already exist. Don't publish again right away. The same goes for an interrupted `publish`. * A first `publish` refused with `busy` created nothing. Run it again after `retry_after_seconds`. * A big game can take minutes, because each media file uploads on its own. Allow the time, or run the command in the background. * If the state file already holds a game, `publish` stops with `project_exists`. Use `update`, or pass a new `--state`. * If your login still waits for approval, `publish` stops with `login_pending`. Approve it, or run `rosebud logout` to publish with a claim link instead. # rosebud connect URL: /docs/cli/connect > Ask the game's owner to approve updates from this CLI. ```sh rosebud connect [--project ] [--agent-client ] ``` `connect` prints a private `approval_url`. The owner opens it, signs in and selects **Allow updates** (**Claim game and allow updates** for an unclaimed game). If the game isn't claimed yet, approving also claims it. ## Options | Option | Details | | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `--project ` | Connect to a claimed game, for example from another computer. Without it, `connect` uses the game in the state file. | | `--agent-client ` | Which tool is asking, shown to the owner. | | `--state ` | The game's state file. Default `.rosebud/project.json`. | ## Example ```sh rosebud connect ``` ```json { "project_id": "6f1d2c8e-...", "status": "pending", "approval_url": "https://rosebud.ai/connect#...", "expires_at": "2026-10-27T18:34:11Z", "claim_expires_at": "2026-10-27T19:04:11Z" } ``` ## Notes * The approval link expires after 30 minutes. Run `connect` again for a new one. * If a connection is already pending or active, `connect` prints it instead of starting another. * Approved access lasts 90 days and covers only this game. See [Sign-in and access](/docs/get-started/access.md). * Not needed for games published with an active login. # rosebud status URL: /docs/cli/status > Check whether this CLI can update the game, and which version is live. ```sh rosebud status [--state ] ``` ## Example ```json { "project_id": "6f1d2c8e-...", "connection_id": "0b7a...", "status": "active", "expires_at": "2027-01-25T18:04:11Z", "title": "Moon Garden", "play_url": "https://rosebud.ai/play/moon-garden", "content_version": "c81d7a33f0...", "saved_content_version": "9f2c41e0b7..." } ``` | Field | Meaning | | ----------------------- | ---------------------------------------------------- | | `status` | `pending`, `active`, `revoked` or `expired`. | | `content_version` | The version live on Rosebud. Only shown when active. | | `saved_content_version` | The last version this CLI published or accepted. | | `approval_url` | Shown again while the connection is pending. | When `content_version` and `saved_content_version` differ, the game changed on Rosebud. See [Publish updates](/docs/guides/publish-updates.md#if-the-game-changed-on-rosebud). # rosebud update URL: /docs/cli/update > Publish a new build of a connected game to the same link. ```sh rosebud update --directory [options] rosebud update --zip [options] ``` `update` makes the game exactly the folder you give it: a file the game has that the folder lacks is removed from the game, and files Rosebud already has aren't uploaded again. It needs an active game connection: approve one with [`rosebud connect`](/docs/cli/connect.md), or publish with an active `rosebud login`, which saves one. ## Options | Option | Details | | --------------------------------------- | ---------------------------------------------------------------------------------------- | | `--directory ` / `--zip ` | The complete new build. Use exactly one. | | `--title ` | A new title. The play link stays the same. | | `--description ` | A new description. An empty value clears it. | | `--thumbnail ` | A new cover. | | `--expected-version ` | The live version you accept replacing, from `pull` or `status`. Needed after a conflict. | | `--state ` | The game's state file. | Details you don't pass stay as they are. ## Example ```sh rosebud update --directory ./dist ``` ```json { "project_id": "6f1d2c8e-...", "play_url": "https://rosebud.ai/play/moon-garden", "content_version": "e4a09b12c6...", "operation_id": "a3c1..." } ``` ## Notes * If the game changed on Rosebud since your last update, `update` stops with `version_conflict` and lists `changed_paths`. Run [`rosebud pull`](/docs/cli/pull.md) to bring those changes in, then update again. See [Publish updates](/docs/guides/publish-updates.md#if-the-game-changed-on-rosebud). * After a pull that reported conflicts, `update` refuses with `pull_conflicts` (exit 2) until a pull reports none or you pass `--expected-version`. An update from a different folder than the last pull refuses with `directory_mismatch` (exit 2): pull into that folder first, or pass `--expected-version` to release it anyway. * `update` has no force option and never merges for you. * If an update is interrupted or its result is unknown (exit 4), run the identical command again with the folder unchanged. It reuses the same operation, sends the media the way the first attempt did, and won't publish twice. If the folder or options changed meanwhile, it refuses with `pending_operation`. * `busy` means Rosebud changed nothing. Run the same command again after `retry_after_seconds`; you may change your files first unless an earlier update is still uncertain. * `project_busy` means Rosebud is generating in the game. Wait for it to finish. # rosebud pull URL: /docs/cli/pull > Bring a game's current files, including edits made in Rosebud, into a folder. ```sh rosebud pull --directory [--force] ``` `pull` downloads the game's text files and media into the folder, creating it if needed. It needs an active [game connection](/docs/cli/connect.md), the game must be claimed, and the game owner's plan must include code download (Rosebud Pro or higher). ## Options | Option | Details | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--directory ` | The folder you publish and update from. | | `--force` | Take Rosebud's copy of every conflicted file, discarding your edits to it, and restore files missing locally. It never touches files changed or added only on your side. | | `--state ` | The game's state file. | ## Example ```sh rosebud pull --directory ./dist ``` ```json { "project_id": "6f1d2c8e-...", "content_version": "e4a09b12c6...", "directory": "./dist", "status": "conflicts", "written": ["src/main.js"], "removed": [], "local_only": ["src/debug.js"], "missing_locally": [], "conflicts": [ { "path": "src/player.js", "reason": "both_changed", "rosebud_copy": ".rosebud/project.remote/src/player.js" } ], "skipped": [], "next_action": "Merge Rosebud's copy of src/player.js into yours, then run rosebud update ..." } ``` If your game has a build step, pull into a new, empty folder such as `./rosebud-files`, copy the changes into your source and rebuild. Then release the build with `--expected-version `. | Field | Meaning | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `written` | Files Rosebud changed or added, now in the folder. | | `removed` | Files Rosebud deleted, now removed from the folder. | | `local_only` | Your own new or changed files. `pull` keeps them, and the next update uploads them. | | `missing_locally` | Files Rosebud and your last sync have but the folder lacks. The next update removes them from the game unless you restore them; `--force` restores them. | | `conflicts` | Files changed on both sides. Your copy stays; Rosebud's copy is saved under `rosebud_copy`. | | `skipped` | Names this disk can't keep, such as a Windows name ending in a dot or space or a device name like `con.js` (`unsafe_path`). The next update removes them from the game unless they're renamed in Rosebud first. | | `status` | `synced`, or `conflicts` while any remain. | ## Conflicts Merge each conflict into your own file, keeping both changes. Rosebud's copies go in a `.remote` folder beside the state file (`.rosebud/project.remote/` for the default state), outside your build folder, so `update` never uploads them. `pull` empties it each time, so don't edit there. | `reason` | Meaning | | ---------------- | ---------------------------------------------------------------------------------------------------------- | | `both_changed` | You and Rosebud both changed the file. Merge both changes into yours. | | `local_deleted` | You deleted it and Rosebud changed it. Restore it from Rosebud's copy, or leave it deleted. | | `remote_deleted` | Rosebud deleted it and you changed it. There's no Rosebud copy: keep the file to restore it, or delete it. | While conflicts remain, `update` refuses with `pull_conflicts`. Pull again until it reports none, or pass the version you merged against: ```sh rosebud update --directory ./dist --expected-version ``` ## Notes * Without code download on the owner's plan, `pull` fails with `plan_required` (exit 3). `publish` and `update` still work: ask what changed in Rosebud before you update, so you don't replace those edits. Don't create a second game to get around it. * `sync_unavailable` (exit 3) means this Rosebud server can't read files back yet, and `unsupported_project` means it can't read this game's files back. Nothing was changed. * If a file changes while `pull` downloads, it stops with `folder_changed` (exit 2) before touching the folder. A download that doesn't match its checksum fails with `download_corrupt` (exit 4) and changes nothing. Either way, run it again. * 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. `update` from a different folder than the last pull refuses with `directory_mismatch`. Pull into that folder first. * `.DS_Store`, `Thumbs.db` and `desktop.ini` are skipped. `pull`'s `next_action` names other hidden files in the folder, such as `.git`, because `update` refuses them. ## Names that differ only by case or Unicode form A name that differs from Rosebud's only by Unicode form (an accented letter stored as one character or two) is the same file on every system. 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. It never replaces a file of your own under another case, and never settles a `name_collision`: rename first. # rosebud disconnect URL: /docs/cli/disconnect > Revoke this CLI's access to the game. ```sh rosebud disconnect [--state ] ``` ```json { "project_id": "6f1d2c8e-...", "status": "revoked" } ``` The game stays online. To update it again, run [`rosebud connect`](/docs/cli/connect.md). Owners can also revoke access in the editor under **Project Settings → Manage connected agents**. # rosebud login URL: /docs/cli/login > Approve this CLI or agent to make assets with your credits. ```sh rosebud login [--agent-client ] [--name