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

# Summer from the Shell skill for AI agents

> Summer as shell commands, no MCP: sign in, run operations, follow jobs, save files, drive the engine. A Summer Engine skill for AI agents.

`summer-cli` is a skill from the [Summer skill library](https://docs.summerengine.com/mcp/skills.md): a guide your AI agent reads when the task matches, so it builds the good version on the first try. Summer as shell commands, no MCP: sign in, run operations, follow jobs, save files, drive the engine.

| | |
| - | - |
| Status | Preview: not yet exercised in-engine by the Summer team |
| Domains | Agent workflow, Asset pipeline, Tools |
| Version | `1.0.2` |
| Recommended set | Yes, installed by `--recommended` |

## When your agent uses it

* The session has no summer\_\* MCP tools, or Summer was set up with summer setup \<agent> --cli
* Running a Summer operation, a generation or an engine change from a shell, a script or CI
* A skill names an MCP tool or an operation and you need the summer command that runs it
* Starting Summer Engine or reconnecting to an existing project

## Install

`summer setup` installs every skill for your agent. To add only this one:

```bash theme={null}
npx -y summer-engine@latest skills install summer-cli --agent claude-code
```

Swap `claude-code` for your agent, such as `codex` or `cursor`. See [Skills](https://docs.summerengine.com/mcp/skills.md#quick-start) for every option.

## The skill

Use this skill when the session has no `summer_*` MCP tools (including after setup, before the host loads them), when Summer Engine needs starting, or when a script or CI job runs Summer. Every Summer capability is an operation named `area.action`, and every operation is one command: `summer <area> <action>`. The commands run the same code as the MCP tools and give the same answers. Missing MCP tools do not mean the engine is stopped: continue through the Summer CLI in this session.

First run `summer --version`. If the shell does not find `summer`, or the version is below 4.0 (an old global install, which has no `summer <area> <action>` commands), put `npx -y summer-engine@latest` in place of `summer`, with the same arguments. In Windows PowerShell, write `npx.cmd`.

## The five commands in a game project

1. `summer run .` opens the project in Summer Engine when run from its root (the folder containing `project.godot`). An agent's run stays in the background. If the engine is not installed, use `summer dev .`; installation needs the person's consent before adding `--yes`. Bare `summer run` fails: always give the project path.
2. `summer engine get-project-context` (MCP: `summer_get_project_context`) verifies the connected project, its main scene and the engine version. Run it before editing; a launch command exiting successfully does not by itself prove the editor is ready.
3. `summer engine play`, then `summer engine get-diagnostics` (MCP: `summer_play`, `summer_get_diagnostics`), runs the game and reads its errors. `summer engine stop` (`summer_stop`) ends it.
4. `summer engine screenshot` (MCP: `summer_screenshot`) saves an image of the editor or the running game. Open its `localPath` to look.
5. `summer ops search "<what you want>"` (MCP: `summer_search`) finds any other operation. Run it as `summer <area> <action>` (MCP: `summer_call`), with `--dry-run` first for a change.

## Start or reconnect to Summer Engine

Use this sequence for both MCP and CLI sessions. Engine commands need no sign-in.

1. **Select the project.** Find its `project.godot` and run commands from that folder. For a new game, follow `new-project`: `summer dev 3d-basic my-game` creates and opens a starter. For an existing game, keep its exact path; do not create a replacement project to recover a connection.
2. **Open it yourself when shell access is available.** Run `summer run .` from the project root, or `summer run "<project-path>"`. This opens an installed Summer Engine; it does not install one. `summer run --no-project` opens the project manager without a project and is not a recovery step for working on a game.
3. **Handle a missing installation.** `summer dev "<project-path>"` opens an existing project and can install Summer Engine if needed. Without consent, a non-interactive call returns `needs_confirmation` and installs nothing. Ask the person once, then repeat the same command with `--yes` only after they agree. Keep any explicit `--bin` / `SUMMER_BIN` selection: an invalid override must be corrected, not silently replaced. Do not substitute a stock Godot executable for Summer Engine.
4. **Wait for readiness.** `summer run` waits up to 20 seconds for the local API; it can exit successfully with an "API not responding yet" message. `summer dev` waits up to 180 seconds and exits with an error if the editor is still opening. Neither message means that another editor should be launched. Follow the output, use `summer status`, and retry the project-context read after 30 seconds if assets are still importing. If it still fails, run `summer doctor` and report the specific blocker instead of repeatedly launching or reinstalling.
5. **Verify before changing anything.** Run `summer engine get-project-context` (or `summer_get_project_context` over MCP) and confirm that the project and engine version are the intended ones. If multiple editors are open, set `SUMMER_ENGINE_PROJECT` to that project's folder for the shell commands. Then continue the requested work through whichever transport is available; missing MCP tools alone do not require a restart to use the CLI.

Without shell access, use `projects.open_local` if the session exposes it (`install: true` only with installation consent), then read project context. If neither transport is available, report that limitation and give the person the exact launch command for their project. Starting the editor cannot make an absent MCP tool appear in the host's tool list.

## 1. Sign in once

```bash theme={null}
summer login     # opens the browser: the Summer account, then the store and cloud operations
summer whoami    # who is signed in, and their credits
```

Cloud operations (generation, the asset library, the store, publishing, analytics) need the sign-in. Engine commands do not. Run `summer login` in the foreground, once. Tell the person that their browser opens, and wait for them.

## 2. Find the operation

```bash theme={null}
summer ops search "make a sound effect"       # the best matches: name, effect, title
summer ops describe assets.generate_audio     # the exact input: fields, types, which are required
```

Describe the job in plain words. `--area assets` keeps one area. Without a sign-in, search and describe still find every operation: a cloud one shows `(needs sign-in)` and runs after `summer login`.

For a guide instead of an operation, search the library: `summer docs search --query "<the task>"`, then `summer docs read --id <id>`. Both work offline. Then follow the skill it names.

Each Summer skill ends with a **From a shell** table: the command for each MCP tool and operation the skill names. A skill that says `summer_play` or `assets.generate_image` means `summer engine play` or `summer assets generate-image`.

## 3. Run it

```bash theme={null}
summer assets generate-image --dry-run --prompt "a cozy pixel-art tavern" --aspect-ratio 16:9
summer engine set-prop --scene-path res://main.tscn --path Player --key position --value "Vector3(0, 1, 0)"
summer store status --game-id <id> --json
```

* Actions and fields are kebab-case: `aspectRatio` is `--aspect-ratio`, `look_at` is `--look-at`.
* `--<field>` alone sets a boolean field to true; `--no-<field>` sets it to false. Repeat a flag to give a list.
* Objects, and anything hard to quote, go in `--input '<json>'`. A flag wins over the same key in `--input`.
* `--dry-run` checks the input and changes nothing. For a spend it shows the estimate in credits. Put it right after the action: after `summer setup <agent> --cli --allow-rules --yes` (run that only when the person asks for it), Claude Code and Codex run it without asking (and the reads). Before each generation or other spend: dry-run it, tell the person what you will make, and wait for a yes.
* `--idempotency-key <key>` makes a retry safe: Summer runs a change once per key.
* `--json` prints only the answer: `{"ok":true,"status":"done","result":{...}}`. The exit code is 0 for every `ok` answer and 1 for an error.

## 4. Long jobs

3D, video, animation, builds and uploads answer `Started: job <id>` with the command that follows the job.

```bash theme={null}
summer assets generate-3d --prompt "a wooden barrel" --wait          # runs, then follows the job to the end
summer jobs wait --job-id <id> --timeout-seconds 50                  # run it again until finished is true
```

Do not run the same change again to get its result. Wait on the job.

## 5. Approvals

A publish or another live change can answer `Needs approval` with a link. Give the person that link: nothing changes until they approve. Follow it with `summer jobs wait --job-id <id>` (or `--wait` on the call) until it ends: `done`, `declined`, `expired` or `stale`. Never approve for the person.

## 6. Files

* `--out <folder or file>` on a generate command, on `summer jobs wait` or on `summer assets get` saves the file there. In a Godot project, `res://` paths work. The answer adds `localPath`.
* Without `--out`, a generation run inside a game project saves into its asset folder: Godot `assets/`, Unity `Assets/Summer`, Unreal `Content/Summer`, three.js `public/assets`. Outside a project, give `--out`.
* `summer assets get --asset-id <id>` saves only with `--out`.
* A save never overwrites a file. Tell the person the `localPath`.

## 7. The engine

Engine commands (`summer engine …`) drive the Summer Engine app on this machine. The app must run with the project open.

```bash theme={null}
summer status                                              # is the engine up, and the sign-in
summer run ./my-game                                       # opens the project; for an agent, in the background
summer engine get-project-context                          # first call: project, main scene, engine version
summer engine get-scene-tree --scene-path res://main.tscn --depth 2
summer engine screenshot                                   # the answer's localPath is an image: open it to look
summer preview                                             # the game, live, in your own browser: http://127.0.0.1:5199
```

* Values are engine value strings, not JSON: `"Vector3(0, 10, 0)"`, `"Color(1, 0.5, 0, 1)"`. A resource is its class name: `"BoxMesh"`.
* Name the scene in every change: `--scene-path res://<scene>.tscn`.
* 3 or more scene edits are one script, not a chain of commands. Write a `func run(ctx):` that ends with `ctx.save_scene()` to a file, then run `summer engine run-script --scene-path res://main.tscn --source "$(cat build.gd)"`. The `scene-scripting` skill has the script API.
* With more than one editor open, set `SUMMER_ENGINE_PROJECT` to the project folder so the command picks the right one.
* To watch the game in your own browser (Claude Code Desktop's Browser pane, the Codex app's in-app browser), run `summer preview` in the background, from the folder the session started in. It serves [http://127.0.0.1:5199](http://127.0.0.1:5199) (the next free port if that one is taken; it prints the URL): the running game, or the editor view when no game runs, with a status line that says what to do next. It also adds a `summer-preview` entry to `.claude/launch.json` there, so Desktop starts it and checks the game after each edit. A game frame comes about every 20 s, because reading one stalls the game; the page's Refresh button takes one now. Keys and clicks on the frame go to the running game. `--no-launch-json` leaves the file alone.
* `summer tool <slug> --args '<json>'` runs an engine tool by its 3.x name too. `summer tool --list` lists them.

## Without Summer Engine

Everything except section 7 works without the app: the sign-in, the library, generation, assets and files, the store and analytics. Skip the `summer engine …` commands; there they answer `engine_not_running`. For assets for another engine or a web app, follow the `summer-assets` skill and stop at the file.

## 8. Errors

An error prints `Error (<code>): <message>` and one `Next:` step, and exits 1. Do the next step. Retry only when the table says so.

| Code | Do this |
| - | - |
| `not_signed_in` | Run the command in `Next` (`summer login`), then the same command again. |
| `engine_not_running` | Follow "Start or reconnect to Summer Engine" above, verify the project context, then retry the operation. |
| `engine_lacks_op` | This engine build is too old for the command. Use the fallback the message names, or ask the person to update Summer Engine. |
| `invalid_input` | `summer ops describe <op>`, fix the flags, run it again. |
| `no_credits` | Give the person the link in `Next`. Do not run it again until they say they added credits. |
| `forbidden` | Summer refused this account. The person checks it in Summer Studio. |
| `not_found` | Check the id (the area's `list` command), or find the right operation with `summer ops search`. |
| `rate_limited`, `unavailable` | Nothing ran. Wait a minute and run it again. If it repeats, tell the person the message. |
| `outcome_unknown` | The change may have run. Run it again only with the same `--idempotency-key`, or check first. |
| `in_progress` | The same change is still running. Wait, then follow its job or run it again with the same `--idempotency-key`. |
| `idempotency_conflict` | That key was used for a different input. A new change needs a new key. |
| `conflict` | The state changed, or a job or approval ended without running (declined, expired, stale or cancelled). Check the current state; start again only if the person wants it. |
| `over_limit` | A plan limit or cap was reached. Give the person the message and the link in `Next`. Do not retry. |
| `unsupported` | Summer cannot do this yet, or not here. Tell the person the message. Do not retry. |
| `internal` | Summer failed on its side. Run it once more; if it fails again, tell the person the message. |

## Done means

* You ran each command and read its answer. Do not report an answer you did not get.
* Every spend had a dry run and a yes from the person first.
* Every file you made is saved, and you told the person its `localPath`.

## Related skills

* [`using-summer`](https://docs.summerengine.com/skills/using-summer): Session bootstrap: how to find and use Summer skills and the summer-engine MCP before any response.
* [`summer-assets`](https://docs.summerengine.com/skills/summer-assets): Game assets for any engine, no Summer Engine: find, generate and download them.
* [`scene-scripting`](https://docs.summerengine.com/skills/scene-scripting): Build scenes, levels, HUDs and wiring with one editor GDScript (summer\_run\_script) instead of call chains.

***

Source: [`library/skills/summer-cli/SKILL.md`](https://github.com/SummerEngine/summer/blob/main/library/skills/summer-cli/SKILL.md), rendered from `summer-engine@4.9.2` on npm.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.