CLI overview

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.

Install

You need Node.js 22 or later. It works on macOS, Linux and Windows.

npm install --global @rosebudai/cli
rosebud --version

Or run any command without installing: npx @rosebudai/cli <command>. 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`	Creates a new game from a build folder or ZIP.
`rosebud connect`	Prints a private link that lets you approve updates from this CLI.
`rosebud status`	Shows whether access is pending, active, revoked or expired.
`rosebud update`	Replaces the game's files and publishes them to the same link.
`rosebud disconnect`	Revokes this CLI's access. The game stays online.
`rosebud pull`	Brings the game's current files, including Rosebud edits, into a folder.
`rosebud login`	Asks you to approve this CLI or agent to make assets with your credits and publish into your account.
`rosebud whoami`	Shows the login's status and your credit balance.
`rosebud logout`	Revokes the login and removes it from this computer.
`rosebud assets models`	Lists models with their inputs, prices and licenses.
`rosebud assets quote`	Checks inputs and prices an asset, free.
`rosebud assets create`	Makes an asset, waits for it and saves the file.
`rosebud assets status`	Shows a job's progress and, when done, its asset.
`rosebud assets list`	Lists your assets, newest first.
`rosebud assets download`	Saves an existing asset's file.

Global options

Option	Default	Details
`--state <file>`	`.rosebud/project.json`	Where the game's details are saved. Use one per game.
`--timeout-ms <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:

{
    "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.
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.

InstallCopy Anchor Link

CommandsCopy Anchor Link

Global optionsCopy Anchor Link

OutputCopy Anchor Link

Exit codesCopy Anchor Link