# SpawnKit CLI reference

Use @spawnkit/cli to create and extend games, connect a project, and manage deployments.

A command-by-command reference to the implemented CLI. Local generation works without an account; hosted operations require access to a project.

<a id="installation"></a>

## Install or run @spawnkit/cli

Install Node.js 24 or newer and pnpm 12. Run the CLI directly without a global install. Both tabs invoke the same @spawnkit/cli package; generated game projects use pnpm for their dependencies and scripts.

**pnpm**

```sh
pnpm dlx @spawnkit/cli --help
pnpm dlx @spawnkit/cli --version
```

**npm / npx**

```sh
npx @spawnkit/cli --help
npx @spawnkit/cli --version
```

The examples throughout these guides use `pnpm dlx @spawnkit/cli`. Replace that prefix with `npx @spawnkit/cli` if you prefer npm to launch the CLI. This does not change the generated project's package manager. See [Create a game with the CLI](https://spawnkit.cloud/docs/create-with-cli) for the complete create, install, run, test, and build sequence.

**Optional global installation**

```sh
pnpm add --global @spawnkit/cli
spawn --help
spawn --version
```

After a global installation, use `spawn` in place of `pnpm dlx @spawnkit/cli`. The package is distributed on [npm](https://www.npmjs.com/package/@spawnkit/cli) and bundles its own runtime dependencies.

<a id="create"></a>

## Discover and create

**Inspect available components**

```sh
pnpm dlx @spawnkit/cli templates --json
pnpm dlx @spawnkit/cli addons --json
```

**Preview, then create a standalone game**

```sh
pnpm dlx @spawnkit/cli init my-game --add phaser,vitest --dry-run
pnpm dlx @spawnkit/cli init my-game --add phaser,vitest
cd my-game
pnpm install
pnpm dev
```

The destination must not exist, even as an empty folder; its parent must exist. Generation writes files but does not install dependencies. Run `pnpm dlx @spawnkit/cli init` without a directory in an interactive terminal for guided setup.

| Option | Behavior |
| --- | --- |
| `--add <names>` | Comma-separated add-ons; repeatable. Use the catalog to check compatibility. |
| `--name <name>` | Package name; defaults to the directory name. |
| `--dry-run` | Show the plan without writing files. |
| `--json` | Machine-readable output; interactive prompts are unavailable. |

<a id="modules"></a>

## Add modules to an existing game

**Review a module addition**

```sh
pnpm dlx @spawnkit/cli add vitest --directory ./my-game --dry-run
pnpm dlx @spawnkit/cli add vitest --directory ./my-game
```

| Option | Behavior |
| --- | --- |
| `--directory <path>` | Existing game folder; defaults to the current directory. |
| `--replace <names>` | Explicitly replace incompatible add-ons; inspect the proposed changes first. |
| `--yes` | Accept a resolved plan. It does not permit overwriting conflicting edits. |
| `--dry-run --json` | Inspect file changes and unresolved choices without writing. |

Read [Updating an existing game](https://spawnkit.cloud/docs/updating) for ownership records, conflict recovery, and verification. Renderer switching is not supported by `pnpm dlx @spawnkit/cli add`.

<a id="account"></a>

## Sign in and select a project

**Authorize and verify a project**

```sh
pnpm dlx @spawnkit/cli login --site https://spawnkit.cloud
pnpm dlx @spawnkit/cli auth status
pnpm dlx @spawnkit/cli link --project YOUR_PROJECT_ID
```

| Command | Contract |
| --- | --- |
| `pnpm dlx @spawnkit/cli login --site <url>` | Open browser authorization. `--no-browser` prints the link instead. `SPAWN_SITE_URL` can supply the site. |
| `pnpm dlx @spawnkit/cli auth status` | Inspect local credentials only; it does not verify remote access. |
| `pnpm dlx @spawnkit/cli link [--project <id>]` | Verify access and save the game folder association. Without an ID, interactive mode offers project selection. |
| `pnpm dlx @spawnkit/cli unlink` | Remove the local association; hosted projects and releases remain. |
| `pnpm dlx @spawnkit/cli login --remote --email <email> --project <id>` | Request one hour of access to one existing project. The owner approves a six-digit code in their browser; no localhost callback is needed. |
| `pnpm dlx @spawnkit/cli logout` | Revoke a remote-agent grant, then remove local credentials. Local OAuth and browser sessions are separate. |

Link and unlink accept `--directory <path>` and `--json`. In the dashboard, open your project → Settings → General → Copy project ID. Replace YOUR_PROJECT_ID with that value and DEPLOYMENT_ID with the relevant deployment ID. See [Accounts and access](https://spawnkit.cloud/docs/authentication) for sign-in recovery.

<a id="deployments"></a>

## Deployment command surface

| Command | Purpose and command-specific flags |
| --- | --- |
| `pnpm dlx @spawnkit/cli deploy` | Upload source and follow the build. `--env sandbox|production`, `--dry-run`, `--yes`, `--no-wait`, `--request-id <id>`. |
| `pnpm dlx @spawnkit/cli releases` | List retained releases. `--cursor <cursor>` paginates results. |
| `pnpm dlx @spawnkit/cli status <deployment-id>` | Read deployment state. Failed, cancelled, or superseded operations return exit code 1. |
| `pnpm dlx @spawnkit/cli logs <deployment-id>` | Read build output. `--cursor <cursor>` resumes pagination; `--follow` or `-f` watches until completion. |
| `pnpm dlx @spawnkit/cli promote <release-id>` | Promote a successful Sandbox release without rebuilding. Supports `--dry-run`, `--yes`, `--request-id <id>`. |
| `pnpm dlx @spawnkit/cli rollback <release-id> --env <environment>` | Activate retained compatible artifacts. Environment is required. Supports `--dry-run`, `--yes`, `--request-id <id>`. |

All deployment commands accept `--project <id>`, `--directory <path>`, `--json`, and `--help`. The project is otherwise inferred from the nearest game folder. Deploy defaults to Sandbox when enabled, otherwise production; specify the environment explicitly when the target matters.

**Inspect before deploying**

```sh
pnpm dlx @spawnkit/cli deploy --project YOUR_PROJECT_ID --env production --dry-run
pnpm dlx @spawnkit/cli deploy --project YOUR_PROJECT_ID --env production
```

> **Source deployment requirements**
>
> The game must include `game.config.json`, `package.json`, and `pnpm-lock.yaml`. Hosted installs use pnpm with a frozen lockfile and lifecycle scripts disabled. Private registries, Git dependencies, and build-time downloads are unsupported. Browser ZIP publishing accepts already-built output instead.

Ctrl+C stops watching, not the remote deployment. Use `pnpm dlx @spawnkit/cli logs DEPLOYMENT_ID --project YOUR_PROJECT_ID --follow` to reconnect. Rollback does not undo database migrations.

<a id="automation"></a>

## Machine output and safe retries

**Noninteractive plan and deployment**

```sh
pnpm dlx @spawnkit/cli deploy --project YOUR_PROJECT_ID --env production --dry-run --json
pnpm dlx @spawnkit/cli deploy --project YOUR_PROJECT_ID --env production --yes --json
```

Successful command results go to stdout. Live deployment logs go to stderr in JSON mode. Login emits newline-delimited authorization and completion records. Check the process exit code and returned status; do not assume that receiving a deployment ID means the build succeeded.

Mutations in noninteractive mode require `--yes`. For retryable deployment mutations, choose a stable `--request-id` for that operation and reuse it only when retrying the same operation. Keep deployment IDs separately from release IDs: status/logs use deployment IDs, while promote/rollback use release IDs.

**Inspect the installed version's contract**

```sh
pnpm dlx @spawnkit/cli --help
pnpm dlx @spawnkit/cli deploy --help
pnpm dlx @spawnkit/cli logs --help
pnpm dlx @spawnkit/cli rollback --help
```