Clone and sync

Start with the case that matches your folder:

• If .sandscape/project.json exists, the folder is already connected. Run sandscape pull before you edit.
• If the folder contains a local game that is not connected, use sandscape init.
• If you want to download a project from Sandscape, list your projects and clone one into a new folder.

The presence of .sandscape/project.json is the reliable test. A generated guide or an agent configuration directory does not prove that the game is connected.

Download a project

sandscape list
sandscape list --no-pick
sandscape list --json
sandscape clone <session_id> ./my-game

sandscape list shows projects you own and projects shared with you. In an interactive terminal, it also lets you choose a project to clone. Use --no-pick to print the list without the picker, or --json for scripts and coding agents.

clone downloads a project into a new directory. If you omit the directory, its name defaults to the session ID.

The target directory must not exist. The CLI verifies each downloaded file and only places the finished clone at the target path after the download succeeds.

Pull, edit, push

Run this loop whenever you work on the game locally:

sandscape pull
# edit the game with your usual tools
sandscape push

pull downloads files that changed on Sandscape. push uploads new and changed local files. Both commands use the current directory unless you pass another connected folder:

sandscape pull ./my-game
sandscape push ./my-game

Resolve conflicting changes

The CLI does not merge two versions of the same file.

• A push is rejected when Sandscape has a newer project version than your clone. The CLI leaves your files alone. Pull the latest version, resolve any conflict, then push again.
• A pull is rejected when the same file changed both locally and on Sandscape. The output lists the conflicting paths and does not overwrite them.
• sandscape pull --force replaces the conflicting local files with the versions from Sandscape.

Files added by the CLI

<game>/
  .sandscape/
    project.json    project ID, synced version, and API origin
    design.json     game concept, style, assets, and development plan
    manifest.json   file checksums used for sync
  CLAUDE.md         generated instructions for coding agents
  AGENTS.md         the same instructions under a second common filename
  .claude/skills/   project copy of the Sandscape skill
  .agents/skills/   shared project copy of the Sandscape skill
  index.html        browser entry point
  <game files>      your existing structure

Do not edit files inside .sandscape by hand. clone and pull update them. Local changes to .sandscape/design.json are not uploaded.

The CLI excludes its metadata and agent files from game uploads.

Progress and limits

clone, pull, push, and init print file progress during a transfer. Add --json to receive one JSON event per line instead.

One file can be at most 50 MiB. One push can contain at most 500 MiB and 5,000 files. See CLI reference for the complete limits and event format.

Common sync errors

• not_a_clone: run the command from a folder that contains .sandscape/project.json, or pass that folder as an argument.
• not_authorized: run sandscape login.
• A skipped file matched an ignore rule, was a symlink, or looked like a credential. Check what syncs and what does not.
• If the clone version is ahead of Sandscape, clone the project again into a fresh directory.