Command reference

Run sandscape --help to print the command summary in your terminal. If you use the CLI through npx, replace sandscape in any example with npx -y @sandscape/cli@latest.

Command summary

Command	Purpose
`login`	Authorize this computer.
`logout`	Remove the saved login from this computer.
`skill install`	Install instructions for coding agents.
`list`	List your Sandscape projects and optionally choose one to clone.
`init`	Connect a local game folder as a new Sandscape project.
`clone`	Download a project into a new folder.
`pull`	Download files that changed on Sandscape.
`push`	Upload new and changed local files.
`publish`	Check, prepare, or publish a game page.

sandscape login [--json] [--api-url <url>]

Starts browser authorization and saves a scoped token on this computer.

Option	Result
`--json`	Prints a `verification` event followed by an `authorized` or `error` event.
`--api-url <url>`	Logs in against a specific trusted backend. Most users should omit it.

See Log in for the browser and coding-agent flows.

`sandscape logout`

sandscape logout [--json]

Deletes the credentials saved on this computer. It does not revoke the token on the server. Revoke the token from your account settings if the computer is no longer under your control.

`sandscape skill install`

sandscape skill install [--here [dir]] [--all] [--harness <names>] [--json]

Installs the sandscape-cli skill for coding agents.

Option	Result
`--here [dir]`	Installs the skill inside one project. The directory defaults to the current one.
`--all`	Installs into every supported global agent directory.
`--harness <names>`	Restricts a global install to comma-separated harness names.
`--json`	Prints the installed targets as JSON.

Valid harness names are claude, codex, cursor, opencode, and agents. Without --here, the command installs globally for detected agents and in ~/.agents/skills.

See Set up the CLI for installation paths and a prompt you can paste into an agent.

`sandscape list`

sandscape list [--no-pick] [--json] [--api-url <url>]

Lists projects you own and projects shared with you. The human-readable output includes the project ID, name, status, and your role.

In an interactive terminal, the command asks which project to clone. Press Enter to skip cloning.

Option	Result
`--no-pick`	Prints the numbered list without opening the clone picker.
`--json`	Prints the complete project array as one JSON document and does not open the picker.
`--api-url <url>`	Uses a specific trusted backend.

`sandscape init`

sandscape init <folder> [--name <name>] [--backfill] [--json] [--api-url <url>]

Creates a new Sandscape project from an existing game folder, uploads its included files, and connects the folder for future sync commands.

Argument or option	Result
`<folder>`	Folder to connect. Required.
`--name <name>`	Project name. The default is derived from the folder name.
`--backfill`	Runs the optional coin-metered AI design pass after import.
`--json`	Prints progress and results as JSON events.
`--api-url <url>`	Uses a specific trusted backend.

The folder must not already contain .sandscape/project.json. Review the root .gitignore and .sandscapeignore before running the command.

See Connect your game.

`sandscape clone`

sandscape clone <session_id> [target_dir] [--json] [--api-url <url>]

Downloads a project into a new folder and connects that folder to Sandscape.

Argument or option	Result
`<session_id>`	Project session ID. Required. Get it from `sandscape list`.
`[target_dir]`	New destination directory. The default is the session ID.
`--json`	Prints download progress as JSON events.
`--api-url <url>`	Uses a specific trusted backend.

The target directory must not exist. A failed clone does not leave a partial target directory.

`sandscape pull`

sandscape pull [target_dir] [--force] [--json] [--api-url <url>]

Downloads new and changed files from Sandscape into a connected folder. The current directory is used when target_dir is omitted.

Option	Result
`--force`	Replaces conflicting local files with the Sandscape versions. This discards those local edits.
`--json`	Prints download progress and conflicts as JSON events.
`--api-url <url>`	Uses a specific trusted backend.

Without --force, the command stops if a file changed both locally and on Sandscape. It lists the conflicts and leaves them untouched.

`sandscape push`

sandscape push [target_dir] [--json] [--api-url <url>]

Uploads new and changed files from a connected folder. The current directory is used when target_dir is omitted.

Option	Result
`--json`	Prints upload progress as JSON events.
`--api-url <url>`	Uses a specific trusted backend.

The command stops if Sandscape has a newer project version. Pull first, resolve any conflicts, then push again. File deletion does not sync in the current protocol.

See Clone and sync.

`sandscape publish`

sandscape publish [target_dir] --check [--json] [--api-url <url>]

sandscape publish [target_dir] --prepare --title <title> [options]

sandscape publish [target_dir] --title <title> [options]

sandscape publish [target_dir] [media options]

The four forms check readiness, prepare a browser review, publish immediately, or work with media without publishing.

Modes

Option	Result
`--check`	Prints readiness, accepted genres, platform values, and the review link. Changes nothing.
`--prepare`	Saves a draft, processes media, and prints a review link. Requires `--title` and does not publish.
`--title` without `--check` or `--prepare`	Publishes immediately after processing any media.
Media flags without a title or mode	Processes the requested media and stops without publishing.

Publishing details

Option	Result
`--title <text>`	Game title. Required for prepare or direct publish.
`--tagline <text>`	One-line hook.
`--genre <name>`	Genre from the list returned by `--check`.
`--short-description <text>`	Short game-card description.
`--long-description <text>`	Full game-page description.
`--description <text>`	Legacy fallback description for direct publishing. Prefer the short and long description options.
`--tags a,b,c`	Comma-separated tags. The selected genre is added to the direct-publish tag list.
`--visibility public	unlisted`
`--platforms desktop	mobile

For direct publishing, the description uses the first nonempty value from --long-description, --short-description, --tagline, and --description.

Media

Option	Result
`--gameplay <path>`	Uploads gameplay video. Limit: 200 MiB.
`--banner <path>`	Uploads cover art. Limit: 10 MiB.
`--generate-banner [direction]`	Generates 16:9 cover art. Pass a specific art direction for better results.
`--thumbnail-url <url>`	Uses an existing thumbnail URL during direct publishing.

Output and connection

Option	Result
`--web-url <url>`	Frontend origin used to format the direct-publish play URL. It does not choose the API backend.
`--json`	Prints phase, upload, preparation, or publication events as JSON.
`--api-url <url>`	Uses a specific trusted backend.

See Publish your game for the recommended review flow.

Options available across commands

Option	Result
`--json`	Uses machine-readable output. Transfers and long operations emit one JSON event per line.
`--api-url <url>`	Sends authenticated requests to a specific backend. Use it only with a backend you trust.
`-h`, `--help`	Prints the CLI usage summary.

For exit codes, environment variables, JSON event shapes, file rules, and limits, see the CLI reference.

On this page