Skip to main content

Overview

The Summer Engine CLI (summer) installs the engine, configures your AI agent, manages projects, signs you in, runs the MCP server, and runs any Summer operation from the shell (summer <area> <action>, see Operations from the shell). Run any command without a global install using npx:
Or install the summer command once and run summer <command>: brew install summerengine/tap/summer (Homebrew) or npm install -g summer-engine (npm, Node 22+). The fastest way to get started is the one-line setup, which wires up your agent’s MCP config, installs the whole skill library, and runs diagnostics in a single step:
Swap claude-code for any id on Every Supported Agent.

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 whole skill library where that agent reads skills, and prints a doctor report. For most agents it also adds the Summer Games MCP (summer-games: friends, parties and messages as you), which you sign in to once on summer.games. Every agent and the files it writes: Every Supported Agent.
Examples:

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.
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.
Platforms: macOS, Windows and Linux (x86_64). On Linux the engine binary goes under ~/.summer/engine/; there is no app bundle. Other systems: summerengine.com/download. What it does: Prints the download URL and size, downloads the latest release (about 1 GB, including Git and other runtime tools), and installs it. It never replaces an installed engine without your yes: the same version exits as up to date, and a different one needs --yes or a confirmation. After install, run summer login, then summer run.

summer login

Sign in to your Summer Engine account via browser OAuth.
What it does: Opens your browser once: you sign in to your Summer account with Google, GitHub, or email, then approve the store, publishing and Grow tools. The CLI saves ~/.summer/auth-token and ~/.summer/oauth-token. One sign-in covers every cloud operation. The MCP server uses a separate local token (~/.summer/api-token) for engine communication.

summer logout

Clear your saved auth tokens.
Removes ~/.summer/auth-token, the store sign-in (~/.summer/oauth-token) and cached user info. Does not affect the engine’s local API token or a SUMMER_TOKEN variable. Run summer login again to sign in.

summer status

Check engine status, API connection, and auth state.
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.
What it does: Finds the Summer Engine binary and launches it with your project. Waits for the local API to respond (up to 20 seconds). If the engine is already running with that project, it reports the version and port and exits. If it is running with another project, it refuses to start a second editor: close or switch the open project first. Examples:

summer open

Open a project in Summer Engine, or open a Summer page or editor surface by name.
What it does: For a project directory: if the engine is not running, it launches with that project. If the engine is already running, it prints a note: to switch projects, close the current one in the engine first, or run summer run <path>. For a destination: it opens the page in your browser or the surface in the editor. --web, --editor, --path, --node, --scene and --param narrow the target; summer open --help lists them.

summer create

Create a new project from a template.
Built-in templates work offline: Library templates (platformers, FPS, racing, roguelikes, multiplayer starters and more) are pinned to one reviewed commit. summer create fetches exactly that commit, checks its tree digest, refuses on a mismatch, and records the pin in the project’s .summer/project.json. Run summer list templates to browse them. Pass --keep-git to keep the fetched .git directory, detached at the pinned commit (the default removes it so you start fresh). Examples:

summer list

List available templates or local projects.
  • templates: Shows the built-in templates and the pinned library templates.
  • 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.
Example:
This is the CLI surface of the same router exposed to agents as the docs.plan operation (3.x name summer_start_game_task).

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

summer mcp

Start the MCP server for AI tool integration.
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. Engine tools keep their names (summer_add_node, summer_run_script, summer_play, summer_screenshot). Cloud work goes through a short list of direct tools plus summer_search (find an operation) and summer_call (run it); after summer login the server carries every cloud operation. See the Operations 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.
Most users never call this directly: summer setup <agent> --yes installs the whole library for you. See Skills for the catalog and where each agent reads skills.

summer tool

Run any Summer tool from the shell, with the same code the MCP runs.
Engine tools need Summer Engine running with the project open.

summer config

Read or change the shared ~/.summer configuration.

summer events

Print recent engine events, or follow them live.
--kinds takes event kinds such as play.started,script.error. --since starts after one sequence number (0 replays what the engine kept). Output is JSON lines when piped. Needs engine 0.5.66 or newer.

summer debug

Write a support-ready Markdown report of what is broken.
--play also launches the game briefly and collects what happened after play.

Operations from the shell

Every Summer operation runs from the shell, with the same input and the same answer as in the MCP. Every operation and its input: Operations reference.
  • Names are kebab-case. The operation assets.generate_image is summer assets generate-image, and its input aspectRatio is --aspect-ratio.
  • Fields: --<field> <value> for each input field; --no-<field> sets it to false; repeat a flag for a list. --input '<json>' passes the whole input, or the parts that are objects.
  • --dry-run: check and describe the call. Nothing changes, nothing is spent.
  • --idempotency-key <k>: the retry key. Operations that go live or move money require it.
  • --wait: follow a job or an approval to the end. The approval link prints first.
  • --json: print the answer envelope only. See How Summer answers.
  • Exit code: 0 for any ok answer (done, running, needs_approval, dry_run), 1 for an error.
Cloud operations run after summer login. Engine and local operations run on your computer and need Summer Engine open; --dry-run checks their input without it. Examples:
summer tool <slug> stays: it runs a tool by its slug or 3.x name.

Environment Variables

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


Next Steps

Skills

Best-practice guides for AI agents

MCP Setup

Connect Cursor, Claude Code, and more

Operations reference

Every MCP tool with parameters

Building a Game

Step-by-step guide for AI agents

Need help? Ask in Discord first. That is where you get the fastest reply and support. For concrete help, email support@summerengine.com or founders@summerengine.com.