> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete reference for the Summer Engine CLI: setup, doctor, install, login, run, create, plan, memory, cloud sync, skills, and the MCP server.

## Overview

The Summer Engine CLI (`summer`) installs the engine, configures your AI agent, manages projects, signs you in, and runs the MCP server. Run any command without a global install using `npx`:

```bash theme={null}
npx -y summer-engine@latest <command>
```

The fastest way to get started is the one-line setup, which wires up your agent's MCP config, installs the recommended skills, and runs diagnostics in a single step:

```bash theme={null}
npx -y summer-engine@latest setup claude-code --yes
```

Swap `claude-code` for any supported agent: `claude-code`, `cursor`, `codex`, `windsurf`, `cline`, `roo-code`, `kilo-code`, `gemini`, `github-copilot`, `vscode-copilot`, `opencode`, `lm-studio`.

***

## Commands

### summer setup

Configure Summer Engine for an AI agent and run diagnostics in one step. This is the recommended onboarding command. It writes the MCP server config for the agent, installs the recommended skills, and prints a doctor report.

```bash theme={null}
summer setup <agent> [--yes] [--scope user|project] [--force]
```

| Argument / Option | Description                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<agent>`         | Agent to configure: `claude-code`, `cursor`, `codex`, `windsurf`, `cline`, `roo-code`, `kilo-code`, `gemini`, `github-copilot`, `vscode-copilot`, `opencode`, `lm-studio` |
| `--yes`           | Apply the practical setup steps (including skill install) without prompting                                                                                               |
| `--scope <scope>` | Config scope: `user` (default) or `project`                                                                                                                               |
| `--dry-run`       | Show planned changes without writing files                                                                                                                                |
| `--print`         | Print the MCP config snippet instead of writing files                                                                                                                     |
| `--force`         | Overwrite existing skill content                                                                                                                                          |
| `--json`          | Print the setup result as JSON                                                                                                                                            |

**Examples:**

```bash theme={null}
npx -y summer-engine@latest setup claude-code --yes
npx -y summer-engine@latest setup cursor --yes --scope project
npx -y summer-engine@latest setup gemini --print          # See the config without writing
```

***

### summer doctor

Diagnose your setup end-to-end: Node version, CLI version, skills freshness, login, engine install, the local engine API, project memory, and MCP server boot.

```bash theme={null}
summer doctor [--json]
```

| Option   | Description               |
| -------- | ------------------------- |
| `--json` | Print diagnostics as JSON |

Run this first whenever something is not working. Each check reports either OK or a clear next step, such as "engine not running" or "not signed in".

***

### summer install

Download and install Summer Engine to your system.

```bash theme={null}
summer install [--path <dir>]
```

| Option         | Description                                                            |
| -------------- | ---------------------------------------------------------------------- |
| `--path <dir>` | Custom install directory (macOS default is `/Applications/Summer.app`) |

**Platforms:** macOS and Windows. Linux users download manually from [summerengine.com](https://www.summerengine.com/download).

**What it does:** Fetches the latest release, downloads the installer, and installs the app. On macOS it mounts the DMG and copies `Summer.app` to Applications. On Windows it runs the installer. After install, run `summer login`, then `summer run`.

***

### summer login

Sign in to your Summer Engine account via browser OAuth.

```bash theme={null}
summer login [--force]
```

| Option    | Description                               |
| --------- | ----------------------------------------- |
| `--force` | Re-authenticate even if already logged in |

**What it does:** Opens your browser to the login page. After you sign in with Google, GitHub, or email, the CLI saves the token to `~/.summer/auth-token`. Login is required for asset search and AI generation tools, and recommended in general. The MCP server uses a separate local token (`~/.summer/api-token`) for engine communication.

***

### summer logout

Clear your saved auth tokens.

```bash theme={null}
summer logout
```

Removes `~/.summer/auth-token` and cached user info. Does not affect the engine's local API token. Run `summer login` again to re-authenticate.

***

### summer status

Check engine status, API connection, and auth state.

```bash theme={null}
summer status
```

Reports whether you are logged in (and with which email), whether the engine is running (and which project and scene are open), and the local API port and token presence.

***

### summer run

Launch Summer Engine, optionally opening a project.

```bash theme={null}
summer run [path]
```

| Argument | Description                                                           |
| -------- | --------------------------------------------------------------------- |
| `path`   | Path to a project directory (must contain `project.godot`). Optional. |

**What it does:** Finds the Summer Engine binary, spawns it with `--editor`, and optionally passes `--path <projectPath>`. Waits for the local API to respond (up to 20 seconds). If the engine is already running, it reports the current state and exits.

**Examples:**

```bash theme={null}
summer run                    # Launch engine (no project)
summer run my-game            # Launch and open my-game/
summer run ./projects/racer   # Launch and open a relative path
```

***

### summer open

Open a project in Summer Engine.

```bash theme={null}
summer open <path>
```

| Argument | Description                                                |
| -------- | ---------------------------------------------------------- |
| `path`   | Path to a project directory (must contain `project.godot`) |

**What it does:** Resolves the path and checks for `project.godot`. If the engine is not running, it launches with that project. If the engine is already running, it prints the path and a note: to switch projects, close the current one in the engine first or run `summer run <path>`.

***

### summer create

Create a new project from a template.

```bash theme={null}
summer create <template> [name]
```

| Argument   | Description                                                        |
| ---------- | ------------------------------------------------------------------ |
| `template` | Built-in slug (`empty`, `3d-basic`) or any community template slug |
| `name`     | Project directory name (defaults to the template slug)             |

**Built-in templates** work offline:

| Template   | Description                                                     |
| ---------- | --------------------------------------------------------------- |
| `empty`    | Empty 3D project with a root Node3D                             |
| `3d-basic` | 3D scene with Camera3D, DirectionalLight3D, floor mesh, and sky |

Community templates clone from `github.com/SummerEngine/template-*`. Run `summer list templates` to browse them. Pass `--keep-git` to keep the upstream `.git` directory after cloning (default is to detach so you start fresh).

**Examples:**

```bash theme={null}
summer create 3d-basic my-game     # Built-in template
summer create empty                # Built-in template
summer list templates              # Browse community templates
```

***

### summer list

List available templates or local projects.

```bash theme={null}
summer list <what>
```

| Argument | Description               |
| -------- | ------------------------- |
| `what`   | `templates` or `projects` |

* **templates:** Shows the built-in templates plus community templates from `github.com/SummerEngine`.
* **projects:** Scans the current directory for subdirectories containing `project.godot`.

***

### summer plan

Plan the right Summer CLI/MCP workflow for an AI game-building task. Takes a goal in plain English and prints the recommended skills, MCP tool groups, host-file work, user gates, and next steps. Useful as a planning aid before you ask your agent to build something.

```bash theme={null}
summer plan <goal...> [--json]
```

| Argument / Option         | Description                                    |
| ------------------------- | ---------------------------------------------- |
| `<goal...>`               | What you want to build, fix, polish, or create |
| `--mode <mode>`           | Optional task mode override                    |
| `--target <target>`       | Optional task target override                  |
| `--asset-policy <policy>` | Optional asset policy override                 |
| `--verification <level>`  | Optional verification level override           |
| `--json`                  | Print the plan as JSON                         |

**Example:**

```bash theme={null}
summer plan make a small arena shooter
```

This is the CLI surface of the same router exposed to agents as the `summer_start_game_task` MCP tool.

***

### summer memory

Inspect a project's durable memory in its `.summer` directory. Project memory is where agents store the game brief, art and audio bibles, the build plan, and locked facts like voice IDs and world canon.

```bash theme={null}
summer memory [--project <path>] [--json]
summer memory show <file> [--project <path>]
summer memory path [--project <path>]
```

| Command                     | Description                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------- |
| `summer memory`             | Print a summary of `.summer` memory: file counts, canonical files, and locked facts |
| `summer memory show <file>` | Print a specific `.summer` Markdown file (must live inside `.summer`)               |
| `summer memory path`        | Print the `.summer` directory path for the current project                          |

| Option             | Description                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `--project <path>` | Project directory to inspect (defaults to the current directory or the running engine's project) |
| `--json`           | Print the summary as JSON                                                                        |

**Example:**

```bash theme={null}
summer memory
summer memory show .summer/memory/casting/voices.md
```

***

### summer cloud

Sync your project with Summer Cloud: the whole project tree, including big binary assets, follows you across machines without Git.

```bash theme={null}
summer cloud init        # Enable Summer Cloud for this project
summer cloud status      # Show what a sync would push, pull, or delete
summer cloud push        # Push local changes (uploads only missing bytes)
summer cloud pull        # Pull cloud changes (verified, checkpointed)
summer cloud restore     # Restore a cloud version or a local checkpoint
summer cloud checkpoints # List local pre-sync checkpoints
summer cloud conflicts   # List or recover preserved conflict files
```

All subcommands take `--project <path>` and `--json`. Requires `summer login`; the engine does not need to be running. See the [Cloud CLI Reference](/mcp/cloud-cli) for every flag and the [Summer Cloud guide](/guides/summer-cloud) for how sync, conflicts, and storage plans work.

***

### summer mcp

Start the MCP server for AI tool integration.

```bash theme={null}
summer mcp
```

**What it does:** Starts the MCP server on stdio. Your IDE or agent invokes this automatically when it loads the MCP config you wrote with `summer setup`, so you rarely run it by hand. Exposes 52 tools for scene editing, debugging, project context, asset search, and AI generation. See the [Tools Reference](/mcp/tools-reference).

There is also a lower-level `summer mcp setup <agent>` subcommand that writes only the MCP config (no skills, no diagnostics). Prefer the top-level `summer setup <agent>` for onboarding.

***

### summer skills

Install and manage best-practice guides for AI agents building games. Skills are Markdown files that teach the agent patterns for scene composition, character controllers, asset generation, debugging, and more.

```bash theme={null}
summer skills list                          # List available skills
summer skills install <name> --agent <a>    # Install one skill for an agent
summer skills install --recommended --agent <a>   # Install the recommended set
summer skills install --all --agent <a>     # Install every skill
summer skills info <name>                   # Show description and preview
```

| Option            | Description                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `--agent <agent>` | Target agent (e.g. `claude-code`, `cursor`, `codex`) so the skill installs where that agent auto-discovers it |
| `--recommended`   | Install the recommended skill set                                                                             |
| `--all`           | Install every available skill                                                                                 |
| `--force`         | Overwrite existing skill content on re-install                                                                |

Most users never call this directly: `summer setup <agent> --yes` installs the recommended skills for you. See [Skills](/mcp/skills) for the full catalog and the 20+ categories.

***

## Environment Variables

| Variable             | Description                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| `SUMMER_GATEWAY_URL` | Override the auth/gateway URL (default `https://www.summerengine.com`). Used for local development. |
| `SUMMER_API_PORT`    | Override the local engine API port if the default 6550 is occupied.                                 |

***

## File Locations

| Path                    | Purpose                                                       |
| ----------------------- | ------------------------------------------------------------- |
| `~/.summer/auth-token`  | User auth token (from `summer login`)                         |
| `~/.summer/user.json`   | Cached user info (id, email, name)                            |
| `~/.summer/api-token`   | Local engine API token (created by the engine on startup)     |
| `~/.summer/api-port`    | Port override if the default 6550 is occupied                 |
| `~/.summer/cloud-token` | Summer Cloud token (from `summer login`)                      |
| `.summer/`              | Per-project durable memory (game brief, bibles, locked facts) |
| `summer-cloud.json`     | Per-project Summer Cloud binding (from `summer cloud init`)   |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Skills" icon="book-open" href="/mcp/skills">
    Best-practice guides for AI agents
  </Card>

  <Card title="MCP Setup" icon="plug" href="/mcp/setup">
    Connect Cursor, Claude Code, and more
  </Card>

  <Card title="Tools Reference" icon="wrench" href="/mcp/tools-reference">
    All 52 MCP tools with parameters
  </Card>

  <Card title="Building a Game" icon="gamepad-2" href="/mcp/building-a-game">
    Step-by-step guide for AI agents
  </Card>
</CardGroup>

***

Need help or have questions? Reach out to our founders at [founders@summerengine.com](mailto:founders@summerengine.com) or join our community on [Discord](https://discord.gg/yUpgtxnZky) for fast responses.