CLI Reference - Summer

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:

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:

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.

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:

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.

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.

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. 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 [--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.

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.

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.

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:

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.

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.

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:

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.

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.

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:

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.

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:

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.

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 for every flag and the Summer Cloud guide for how sync, conflicts, and storage plans work.

summer mcp

Start the MCP server for AI tool integration.

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 tools for scene editing, debugging, project context, asset search, and AI generation. See the 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.

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 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.

There is no environment variable for the engine port. The CLI reads the port from the ~/.summer/api-port file listed below, which the engine writes on startup, and falls back to 6550 when that file is absent.

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

Skills

Best-practice guides for AI agents

MCP Setup

Connect Cursor, Claude Code, and more

Tools Reference

Every MCP tool with parameters

Building a Game

Step-by-step guide for AI agents

Need help or have questions? Reach out to our founders at founders@summerengine.com or join our community on Discord for fast responses.

​Overview

​Commands

​summer setup

​summer doctor

​summer install

​summer login

​summer logout

​summer status

​summer run

​summer open

​summer create

​summer list

​summer plan

​summer memory

​summer cloud

​summer mcp

​summer skills

​Environment Variables

​File Locations

​Next Steps