Rosebud AIDocs
CreatePlayMy assets
Get startedGuidesCLIHTTP APIModels

rosebud pull

Bring a game's current files, including edits made in Rosebud, into a folder.

rosebud pull --directory <folder> [--force]

pull downloads the game's text files and media into the folder, creating it if needed. It needs an active game connection, the game must be claimed, and the game owner's plan must include code download (Rosebud Pro or higher).

Options

OptionDetails
--directory <folder>The folder you publish and update from.
--forceTake 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 <file>The game's state file.

Example

rosebud pull --directory ./dist
{
    "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 <content_version from the pull>.

FieldMeaning
writtenFiles Rosebud changed or added, now in the folder.
removedFiles Rosebud deleted, now removed from the folder.
local_onlyYour own new or changed files. pull keeps them, and the next update uploads them.
missing_locallyFiles 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.
conflictsFiles changed on both sides. Your copy stays; Rosebud's copy is saved under rosebud_copy.
skippedNames 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.
statussynced, 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.

reasonMeaning
both_changedYou and Rosebud both changed the file. Merge both changes into yours.
local_deletedYou deleted it and Rosebud changed it. Restore it from Rosebud's copy, or leave it deleted.
remote_deletedRosebud 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:

rosebud update --directory ./dist --expected-version <content_version from pull>

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 update

Publish a new build of a connected game to the same link.

rosebud disconnect

Revoke this CLI's access to the game.

On this page

OptionsExampleConflictsNotesNames that differ only by case or Unicode form