CLI reference

The private @scape/cli package provides the scape command for Gizmo projects and persistent agents. Use Node.js 22 or newer and Yarn. Run yarn scape --help from an installed kit or source workspace. An operator can export the initial kit from source. Gizmo scaffolding requires an existing Gizmo kit, containing all three private archives; an agent-only kit cannot scaffold a working Gizmo project. Source users should export with yarn sdk:starter below, and agent-kit users should obtain a Gizmo kit first.

Command	Purpose
scape gizmo init <new-directory>	Create a blank project from an installed Gizmo kit, carrying all three private archives forward
scape gizmo dev --origin <https-url>	Build, watch and connect a Gizmo project
scape agent init <new-directory> [--provider <name>] [--model <id>] [--base-url <url>]	Create an independent agent project with provider configuration and private archives
scape agent run [--origin <https-url>]	Guided setup and pairing on first use, then run the saved agent
scape agent configure [--origin <https-url>]	Edit the saved agent through prompts
scape agent login [--origin <https-url>]	Pair and save access without entering a world
scape agent status	Check local configuration/process and saved remote access
scape agent run --project <directory> --origin <https-url>	Run an explicit code project instead of the managed profile
scape agent mcp config --origin <https-url>	Print configuration for an MCP host
scape agent mcp serve --origin <https-url>	Start the stdio MCP server

scape init and scape dev remain compatibility aliases. New projects use the namespaced commands. HTTPS is required except for loopback development.

Export a Gizmo kit

Run from an installed Scape source workspace:

yarn sdk:starter /new/project/directory

The destination must be new and its parent must already exist. Add --template with counter, voting-booth, lamp, pressure-pad, fan, walkable-tile, chime, or jump-pad for an example. Omit it for a blank project.

The export includes three private archives: scape-sdk.tgz, scape-cli.tgz and scape-agent-mcp.tgz in vendor/. The manifest points to local SDK/CLI archives and uses a Yarn resolution for the transitive MCP package. Keep all three archives and those resolutions. Public third-party dependencies still require installation; the kit is not fully offline. Export never overwrites an existing project.

Work inside a kit

yarn install
yarn build
yarn dev --origin https://your-scape-host

The dev script invokes scape gizmo dev. You can also run yarn scape gizmo dev --origin https://your-scape-host directly. The default source entry is src/definition.ts; new kits set scape.entry to src/project.ts in package.json. The CLI watches build inputs and package metadata, embeds supported assets, and uploads accepted build candidates.

With the kit's CLI installed, create another blank project using:

yarn scape gizmo init /new/other-project

See Gizmo quickstart for the approval flow.

Persistent agents

scape agent run works without an agent project. On first use it prompts for identity, provider/model/key and the Scape URL, then guides owner approval. Further runs reuse the local profile and check saved access. scape agent is a shortcut for scape agent run; scape agent init without a directory opens configuration only. Stop the running agent before configure or login. Noninteractive runs need a configured profile and valid saved approval; they exit with an actionable message if input or new approval is needed.

Profiles default to ~/.scape; use SCAPE_CLI_HOME for a separate dedicated profile. Keys are hidden during entry and stored with owner-only file permissions on macOS/Linux, without encryption. Environment keys can stay out of the profile. Status never prints credentials and does not enter the world or call a model. NO_COLOR=1 disables color/animation; SCAPE_REDUCED_MOTION=1 disables animation only. Piped output stays plain. MCP configuration and stdio output always remain machine-readable.

For a ready-made persistent runner, use Run a persistent agent. Optional code projects contain two private archives: CLI and MCP, with no Gizmo SDK dependency. init prompts for provider/model on an interactive terminal; flags support noninteractive setup. --base-url applies to openai-compatible. If fields are missing in noninteractive setup, edit scape.agent.json before running. Setup never overwrites an existing directory. See Agent configuration for exact fields and defaults.

Configure MCP

The MCP commands below are the lower-level interactive testing workflow.

Run from an installed kit or the installed Scape source workspace:

yarn --silent scape agent mcp config --origin https://your-scape-host

This prints absolute Node/script paths suitable for your MCP host. It contains no bearer or model key. SCAPE_AGENT_ASSET_DIR, when set, is included as an environment field.

The generated configuration invokes Node directly with an absolute adapter path. Copy that command and its arguments into your MCP host; do not replace it with Yarn, whose banners interfere with the stdio protocol. Paths resolve to the local installation, so a kit does not need a Scape source checkout.

The equivalent unified server command is scape agent mcp serve --origin https://your-scape-host. It serves MCP over stdin/stdout; it does not start a model or decision loop. There is no hosted MCP URL. Agent pairing is separate from Gizmo upload approval. Use Test through MCP for interactive host configuration, or Run a persistent agent for the main development path.

The standalone scape-agent-mcp command and repository yarn agent:mcp alias still work. yarn agent remains manual transport diagnostics. These commands do not introduce a second AI gameplay interface.

Environment summary

Setting	Used by	Purpose
scape.entry in package.json	Gizmo CLI	Project entry file
SCAPE_AGENT_ASSET_DIR	MCP server	Dedicated approved avatar directory
SCAPE_AGENT_TOKEN	MCP server	Optional operator-supplied existing scoped grant; never put it in a prompt
Model provider variables	Your runner	Inference configuration, outside Scape's tool arguments