CLI reference

Help and project paths#

Run mockspace --help to print the command surface. Commands that operate on an application accept --project <dir>; it defaults to the current directory. Mockspace requires Node.js 20.6 or newer.

Mockspace does not implement init or doctor commands.

Validate and view#

mockspace check --project <dir> loads the workspace, validates declared source paths, states, and edges, and prints the configured application start command. It does not start the app.

mockspace dev --project <dir> [--port 4310] starts the live viewer, fixture proxies, and HTTP RPC. Start the configured application separately. The viewer defaults to port 4310 and prints its actual URL.

Capture#

mockspace build --project <dir> [--out dist] captures every declared frame into a static, inert export. The application must be running at app.url.

Useful build options:

• --app <url> captures from that origin instead of the configured app URL.
• --only <frame,prefix> recaptures matching frame IDs or prefixes.
• --reuse <dir> supplies unchanged frames for an incremental capture. The existing output directory is the default reuse source.
• --port <number> selects the internal viewer/proxy base; build offsets it so a running dev viewer can remain in place.

Build reports frame failures, captures that never became quiet, and pages that kept the network busy. A failed frame remains visible as an error card and causes a nonzero exit.

Publish#

mockspace publish --project <dir> [--dist dist] --service <url> uploads a validated static build. --token <secret> overrides environment or saved credentials.

Publish metadata options include --as, --branch, --commit, --by, --name, --label, --pr, --base, --origin, --thumb, --visibility private|project, and --owner. --not-latest prevents the upload from moving the latest ref. Branch and author otherwise use CI metadata or local Git when available.

Publishing does not build automatically. Capture and inspect dist first.

Sign in#

mockspace login --service <origin> [--no-browser] authorizes this computer. The headless form prints a URL and accepts a short-lived code copied from the browser.

mockspace whoami [--service <origin>] prints the saved identity and expiry for one service, or every saved service when omitted.

mockspace logout --service <origin> removes that service's saved login from this computer. Explicit token flags and environment credentials are separate and continue to take precedence.

Saved agents#

mockspace agent list --service <origin> --project <name> lists your agents, including disconnected work. For these commands, --project is the service’s project name, not a filesystem path.

mockspace agent restore --service <origin> --project <name> --session <id> reads that specific agent’s saved context and prints a restore prompt with recent work. Paste the prompt into the agent that should continue. --json returns the full saved session and recovery instructions. Reading does not take over the connection; the agent explicitly calls restore_agent to claim it. See agent recovery.

Both commands accept MOCKSPACE_SERVICE and the normal saved CLI login, environment token or --token. The loopback preview works without sign-in. They never infer the project or choose the most recently active agent.

MCP#

mockspace mcp --project <dir> runs standalone local context over standard input and output.

mockspace mcp --connect <url> [--project <dir>] [--token <secret>] binds the process to one live canvas or hosted review. A hosted connection uses the matching local project for policy-controlled source tools.

mockspace mcp --service <origin> [--project <dir>] [--token <secret>] provides one stable relay for published reviews on a service. The selected review is supplied later through shared context.

Read MCP for client registration and the difference between direct hosted OAuth and the CLI relay.

Warm a development app#

mockspace warm --project <dir> [--app <url>] requests every declared state URL once. It is useful when a development server compiles routes on first request. The command reports status and timing and exits nonzero when a route fails.

Workbench automation#

mockspace workbench <command> operates durable design requests and prints one JSON value. Supported commands include state, get, next, queue, request, claim, transition, urgency, worked, candidate, message, events, next-chat, watch, attach, heartbeat, and detach. request --urgency and urgency <id> <level> set where a request sits in the queue (low, normal, high, or urgent, which needs the project's review role); urgency never skips an approval.

Workbench service resolution is --service, then MOCKSPACE_SERVICE_URL, then MOCKSPACE_SERVICE. Project resolution is --project, then MOCKSPACE_PROJECT. Use command help and the installed design-request skill for the request lifecycle; do not treat it as a general shell API.

mockspace chat-window runs the zero-token-idle realtime workbench adapter. It accepts --service, --project, and --token; additional runtime policy comes from the documented MOCKSPACE_WINDOW_SECONDS, MOCKSPACE_CHAT_MODEL, MOCKSPACE_SESSIONS_DIR, and MOCKSPACE_WORK_DIR environment variables.

Credential precedence#

Where a token is accepted, the CLI resolves an explicit --token, then MOCKSPACE_TOKEN, then machine-token environment configuration, then the saved login. Prefer a personal login on a person's computer and a machine token only for controlled automation.