godot-cli 0.38.0 → 0.39.1

package/CHANGELOG.md

@@ -4,6 +4,111 @@ All notable changes to `godot-cli` are documented in this file.
 
 ## Unreleased
 
+- **Dependencies:** commander 15, chalk 6, yocto-spinner 1.2.2; dev: TypeScript 7 (native compiler), vitest 5.
+  Two visible changes, both from commander: a call with too many arguments now names them
+  (`error: too many arguments for 'check'. Expected 1 argument but got 2: a, b.`), and a negative number such as `-5` is
+  read as an argument (`exec -1`, `rql --schema -1`, `run-script x.gd -5`) instead of failing with `unknown option '-5'`.
+  commander 15 and chalk 6 declare
+  Node.js >= 22.12 / >= 22; `@baizor/gamedev-cli-core` already required Node.js >= 22.14.
+- **A connection dropped mid-call exits 7 `UNREACHABLE`.** A socket the server took and then closed — before the
+  answer's headers, in the middle of its body, a reset (`ECONNRESET`, `EPIPE`, undici's `UND_ERR_SOCKET` "other side
+  closed" / "terminated") — now fails `run-tool`, `run-system-tool`, `exec`, `rql` and `tools` with exit **7** `UNREACHABLE`
+  (`connection-reset`), the same in all three engine CLIs (one helper, `networkFailureReason` of
+  `@baizor/gamedev-cli-core` ^0.11.1). It was exit 1 `ERROR`, and a body cut off after a 200 was read as an empty
+  answer. A connect timeout or an unreachable host (`ETIMEDOUT`, `EHOSTUNREACH`, `ENETUNREACH`) is exit 7 too (was 1).
+  `tools` fails the same way (exit 7) when no cached list exists: a server that dropped the connection is no longer
+  answered with the built-in list, which stays for an editor that is not running.
+- **One failure table shared with `unity-mcp-cli` and `unreal-mcp-cli`.** A failed `run-tool`, `run-system-tool`,
+  `exec`, `rql` or `tools` call is classified by `classifyToolFailure` of `@baizor/gamedev-cli-core` ^0.11.0, so all
+  three engine CLIs give the same exit code and error code (table in the README, `errorCodes` in
+  `commands --format json`). The envelope error carries the server's HTTP status: `errors[{code, message, httpStatus}]`.
+  Behaviour changes:
+  - HTTP 404 (no such tool): exit **2** `NOT_FOUND` (was 6 `TOOL_FAILED`); `tools <name>` with no such tool: exit **2**
+    `NOT_FOUND` (was 6).
+  - HTTP 401 / 403: exit 6 `NOT_AUTHENTICATED` (was 6 `TOOL_FAILED`).
+  - HTTP 400 and any other 4xx: exit **2** `USAGE` (was 6 `TOOL_FAILED`); a 422 whose error starts with
+    `[invalid_params]` is `USAGE` too.
+  - HTTP 408: exit 14 `TIMEOUT`; HTTP 429: exit 17 `BUSY` (were 6 `TOOL_FAILED`).
+  - HTTP 503 whose error says no engine plugin is connected: exit **7** `UNREACHABLE` (was 17 `BUSY`).
+  - An editor start that waited out another CLI call's start lock: exit **17** `BUSY` (was 7 `UNREACHABLE`).
+  - A path that does not exist or is not a Godot project (no `project.godot`): error code `NOT_FOUND` (was `USAGE`;
+    exit 2 either way).
+- **`close` stops the editor's local MCP server too.** The addon runs `gamedev-mcp-server` as a child of the editor and
+  stops it when the editor quits cleanly, but `close --force` hard-kills a GUI editor without its children, so the
+  server kept running. `close` now notes the servers in that editor's process tree before closing it (by parentage, not
+  by command line) and, once the editor is gone, kills each one still running with the processes it started, after
+  checking its PID still names the same process. Another project's or editor's server is never touched.
+- **ReflectorNet 5.5.2.** The `install-plugin` fallback pin (addons without `nuget-deps.json`) follows the addon: its
+  reflection caches no longer reserve storage for their full capacity up front (about 1 MB less per converter).
+- **`run-tool` no longer prints a screenshot's base64 in text mode.** A tool answer with an image fell back to the whole
+  response JSON, so one `screenshot-viewport` call wrote about 2 MB to stdout. The JSON now names the image's size
+  instead of its data; `--format json` and `--raw` keep the data, and a screenshot tool's `savePath` writes a file.
+- **`setup-skills` writes a cold-start `godot-cli` skill** instead of the outdated install guide and the ten
+  hand-written tool-family skills: no `status` / `run-tool rql-schema` first, `rql` recipes, `check` / `test`,
+  `--format json` and the exit codes, with `references/rql.md` and `references/install.md` for depth. Offline, from
+  the same source as the root `--help` (`src/lib/cli-guide.ts`). The `godot-mcp*` skills of earlier versions are
+  removed; the addon's own install guide is now `godot-cli-install`, so the editor no longer overwrites `godot-cli`.
+  The skill shows every `rql` recipe, among them a Godot property or script variable by name (`props["..."]`);
+  `references/rql.md` holds the language. Its description says it is for editor work and that editing scripts alone
+  needs only `check`.
+- **`rql '<query>'`: one RQL query without JSON quoting.** A query ending in `set` / `call` goes to `rql-mutate`
+  (`--dry-run`, `--max-targets`), any other to `rql-query`; `--schema [type]` runs `rql-schema`; `-f <file>` / `-f -`
+  reads the query. After a save (`SaveScene()`, `NewScene(...)`, resource edits) it lists the files written, and an
+  operator spelled as in another language (`startsWith`, `like`) gets a hint.
+- **`run-tool` text mode prints the answer alone**: a text answer as its text, without the heading, the Tool / URL /
+  Auth lines, the divider and the spinner lines (`--verbose` adds the endpoint; status lines go to stderr; `--raw` and
+  `--format json` are unchanged).
+- **A shorter root `--help` (5.7 KB -> 1.7 KB)**: the everyday commands, the other command names and seven RQL recipes;
+  a subcommand's help starts with a plain line instead of a box.
+- **The exit codes, `--format`, the result envelope, the `commands` manifest and the local-server fallback rule
+  now come from `@baizor/gamedev-cli-core` 0.9.0** (one contract for the three engine CLIs). `commands --format json` lists the commands in registration order, adds `globalOptions` and option `choices`, leaves out hidden options (`close --url`) and has reworded exit-code descriptions; `--format` is trimmed, the last one on the command line wins (up to `--`), and a bad value reports `--format must be one of: …`; a `UsageError` reaching the entry point exits 2 (`USAGE`); the envelope is written synchronously, and a json/ndjson command that exits without one still leaves one on stdout. An unreadable
+  sign-in no longer prints PowerShell's DPAPI exception, and a forced close of an editor godot-cli started also kills its
+  child processes.
+- **`tools [name]`** lists the editor's AI tools (MCP `tools/list`, starting a headless editor when none answers; cached in
+  `.ai-game-dev/tools.json`), and with a name shows its arguments and an example `run-tool` call. A tool that does not
+  exist (HTTP 404) now prints the server's error and points to `godot-cli tools`; the raw response only with `--verbose`.
+  The root `--help` ends with the everyday workflow.
+- **`open` on a machine that never signed in** gives the editor the project's local server (Custom, the plugin starts
+  it; in memory, nothing is persisted) instead of a Cloud connection that cannot work, so `wait-for-ready` / `run-tool`
+  reach it. `status` and `wait-for-ready` follow the project's connection mode like `run-tool`.
+- **A signed-in machine is never switched to a local server.** On a Cloud project, `open --headless` (and the
+  auto-start of `run-tool` / `tools`) no longer starts an editor on the project's local server: a sign-in that cannot be
+  used fails with its sign-in message (exit 6), a working one says to use `open`, `run-tool` and `exec`, which go
+  through ai-game.dev (exit 6). A windowed `open` with an unusable sign-in also exits 6 instead of starting an editor
+  on a connection it cannot use. `exec` calls a non-local `--url` / `GODOT_MCP_HOST` directly instead of starting an
+  editor on the local port, and `GODOT_MCP_CLOUD_URL` no longer turns a Custom project into a Cloud one.
+- **`close` closes an editor godot-cli started** through its plugin (as `--owned-only` does) instead of a window close it
+  cannot receive. For an editor run by the `_console` build (no window of its own), a plain `close` asks the editor window
+  it runs to quit; **`close --force`** stops such an editor and its child process; `close` and `setup-skills` accept `--path`.
+- **A C# build that fails before an editor start** is reported as its compiler errors (`file(line,col): error CS…`), and
+  an editor that never became ready points to `godot-cli check`.
+
+- **Headless commands that judge Godot by its log, not its exit code** (an `--import` with a GDScript parse error or an
+  addon that fails to load still exits 0). `check [path] [--strict]`: a CI gate without an editor (import, `dotnet
+  build`, editor boot with the addon's load marker, a load of every GDScript) reporting `res://file:line` and
+  `file(line,col): error CS…`. `test [path]`: GUT or gdUnit4, headless, hard timeout, verdict from the JUnit report
+  cross-checked with the log (a test script that fails to load does not pass); `--filter`, `--output`, `--format github`.
+  `export <preset> <output> [--debug|--pack]`: checks the templates first and the output file and log afterwards.
+  `import [path]`, and `run-script <file.gd>` (one-shot `SceneTree` script, exit from `quit(code)`). They refuse a
+  project open in an editor (`PROJECT_OPEN`, `--allow-open` overrides). Library: `checkProject`, `importProject`,
+  `runTests`, `exportProject`, `runScript`, `parseGodotLog`, `parseJUnit`.
+- **Exit codes and `--format` shared with unity-mcp-cli and unreal-mcp-cli.** 0 success, 1 unclassified, 2 usage
+  (also unknown options, which exited 1), 6 command failed (a tool answering `status: "error"` or an HTTP error
+  other than 502/503/504, script or compilation errors), 7 unreachable (was 1; also HTTP 502), 8 tests failed (a
+  suite-level setup/teardown failure counts), 14 timeout (`wait-for-ready` timed out with 1; also HTTP 504), 17 busy
+  (HTTP 503), 18 awaiting input. A headless run stopped by Ctrl+C / SIGTERM kills the Godot process tree and exits 1.
+  `--format text|json|ndjson` on `run-tool`, `run-system-tool`, `exec`, `status`, `wait-for-ready` and the new
+  commands: one `{success, command, data, errors, warnings}` envelope on stdout (also for argument errors), logs on
+  stderr (ndjson: one JSON event per line). `commands [--format json]` prints a manifest of every command, its
+  arguments and options, and the exit codes.
+- **`run-tool`, `run-system-tool` and `exec` follow the project's connection mode.** Without `--url` / env / marker they
+  read the mode the addon uses (env, project `.env`, persisted config, default Cloud): Cloud goes to ai-game.dev with
+  the sign-in; a machine that never signed in falls back to the project's local server with a warning; a sign-in that
+  cannot be used fails with `NOT_AUTHENTICATED` (exit 6) instead of switching to a local server.
+- **`run-tool` / `run-system-tool` start a headless editor** when the call is refused on the project's local server,
+  like `exec` (a running editor is reused and never closed). `--no-start` turns it off; `--once` closes the editor
+  afterwards when this call started it; `--no-build`, `--editor-path`, `--ready-timeout`.
+
 - **`update` updates everything.** `update [path]` brings the project's addon and installed extensions to their latest
   versions, then updates the CLI itself (it used to update only the CLI). From a subfolder it finds the project; outside a
   project it updates only the CLI. `--check` reports (exit 2 when something is outdated); `--no-self`, `--no-project` and

package/README.md

@@ -43,7 +43,7 @@ The CLI is the Godot analog of [`unity-mcp-cli`](https://www.npmjs.com/package/u
 - :white_check_mark: **Status check** — detect a running Godot editor and probe MCP-server health
 - :white_check_mark: **Run tools** — execute MCP and system tools directly over the server's HTTP API
 - :white_check_mark: **Setup MCP** — write AI-agent MCP-client config for any supported agent
-- :white_check_mark: **Setup skills** — generate Godot-MCP skill files locally (no live editor required)
+- :white_check_mark: **Setup skills** — write the cold-start `godot-cli` agent skill locally (no live editor required)
 - :white_check_mark: **Wait for ready** — poll until the Godot MCP server answers `ping`
 - :white_check_mark: **Cross-platform** — Windows, macOS, and Linux
 - :white_check_mark: **Library API** — a side-effect-free, typed library surface for embedding
@@ -89,15 +89,23 @@ npx godot-cli install-plugin /path/to/godot/project
 | `open [path]` | Build the project's C# assembly (so the addon loads on first open — see below), resolve the Godot editor binary, and launch `--editor --path <project>` with `GODOT_MCP_*` connection env vars. `--no-build` skips the build. `--headless` starts a windowless editor session instead (see [`exec`](#exec)). |
 | `exec [code]` | Run C# in the editor through `script-execute` (see [`exec`](#exec)): reuses a running editor, otherwise starts a headless one and keeps it warm. |
 | `build [path]` | Build the project's C# assembly (`dotnet build`) so the `godot_mcp` addon loads on the next editor open. GDScript-only projects (no `.csproj`) are a no-op. This is the same build `open` runs before launching. |
-| `run-tool <tool> [path]` | POST to `<url>/api/tools/<tool>` with JSON input. |
-| `run-system-tool <tool> [path]` | POST to `<url>/api/system-tools/<tool>` (tools not exposed to MCP clients). |
+| `rql [query]` | One RQL query from the command line, no JSON: `godot-cli rql 'nodes \| where name starts-with "Tree" \| count'`. A query whose last stage is `set` or `call` goes to `rql-mutate` (`--dry-run`, `--max-targets <n>`), any other to `rql-query`; `--schema [type]` runs `rql-schema`; `-f <file>` (`-f -`: stdin) reads the query when a shell strips its quotes. Starts a headless editor like `run-tool`. After `SaveScene()`, `NewScene(...)`, `CreateResource(...)` or a `godot.resource(...)` edit it prints the files written (`Saved to disk: res://scenes/forest.tscn`); an operator spelled as in another language (`startsWith`, `like`) gets a hint with RQL's spelling. `rql --help` lists recipes. |
+| `run-tool <tool> [path]` | POST to `<url>/api/tools/<tool>` with JSON input. Text mode prints a text answer as its text (`--raw`: the response JSON; `--verbose`: also the endpoint). When no editor answers on the project's local server it starts a headless one like `exec` (`--no-start` disables; `--once` closes it after the call). |
+| `run-system-tool <tool> [path]` | POST to `<url>/api/system-tools/<tool>` (tools not exposed to MCP clients). Same auto-start as `run-tool`. |
+| `check [path]` | CI gate without a running editor: import, `dotnet build`, editor boot and a GDScript load check, judged from the logs (see [headless commands](#headless-commands-check-import-test-export-run-script)). |
+| `import [path]` | `godot --headless --import`, failing on import and script errors in the log. |
+| `test [path]` | Run the project's GUT or gdUnit4 tests headless with a hard timeout; verdict from the JUnit report and the log. |
+| `export <preset> <output>` | Export a preset headless (`--debug`, `--pack`); checks the export templates first and the output afterwards. |
+| `run-script <script> [args...]` | Run a one-shot `SceneTree` GDScript (`godot --headless -s`); exit 0 only after `quit(0)`. |
+| `commands` | Machine-readable manifest of every command, its arguments and options, and the exit codes (`--format json`). |
+| `tools [name]` | The editor's AI tools (MCP `tools/list`; starts a headless editor when none answers, caches the list in `.ai-game-dev/tools.json`, git-ignored). With a name: its description, arguments and an example `run-tool` call. `--refresh` asks the editor again; `--no-start` uses the cache or the built-in list. |
 | `status [path]` | Detect a running Godot editor for the project and probe MCP-server health. |
 | `wait-for-ready [path]` | Poll the MCP server until it answers `ping`. |
 | `login [path]` | Authenticate with the ai-game.dev cloud via the OAuth 2.1 device-authorization flow (RFC 8628) — opens a browser, then saves a cloud credential to the shared machine store (`~/.ai-game-dev/credentials.json`) the editor plugin auto-adopts. See the `login` section below for its `--project` / `--base-url` / `--force` / `--tools-only` / `--yes` flags. |
 | `setup-mcp <agent> [path]` | Write the agent's MCP-client config pointing at the project-pinned `<host>/mcp/p/<pin>` URL (so the agent routes to *this* project's editor). In Cloud mode the config carries this project's key (`Authorization: Bearer agd_pk_…`). Add `--no-pin` for the bare `<host>/mcp` URL, `--oauth` for a URL-only config, `--regenerate-key` to replace the key. |
-| `setup-skills <agent> [path]` | Generate Godot-MCP skill files (a `SKILL.md`-per-tool-family) under the agent's skills path. `--list` shows each agent's skills support. |
+| `setup-skills <agent> [path]` | Write the `godot-cli` agent skill (cold-start workflow, RQL recipes, exit codes) and `ai-game-dev-app` under the agent's skills path, offline. `--list` shows each agent's skills support. |
 | `configure [path]` | List / show / hide tools, prompts, and resources in the project-local `.godot-mcp/features.json` (`--enable-*` shows, `--disable-*` hides; a hidden tool still runs when called by name). |
-| `close [path]` | Gracefully stop the Godot editor running for a project (`--force` to hard-kill). `--owned-only` closes only an editor `godot-cli` started (`exec` / `open --headless`). |
+| `close [path]` | Gracefully stop the Godot editor running for a project (`--force` to hard-kill). Also stops the local MCP server that editor ran, if it outlived it. `--owned-only` closes only an editor `godot-cli` started (`exec` / `open --headless`). |
 | `install-plugin [path]` | Install the `godot_mcp` addon end-to-end: materialize `res://addons/godot_mcp/` (download the matching GitHub release, or `--source <path>` a local copy), add the NuGet `PackageReference`s the installed addon needs + the extension-catalog `<EmbeddedResource>` to the project `.csproj`, and enable the plugin. Idempotent. |
 | `install-extension <id> [path]` | Install a Godot-MCP **extension** (an optional RQL-module package) into the project: resolve `<id>` from the shared catalog, add/update its `<PackageReference>` in the project `.csproj`, then rebuild to restore. Idempotent — behaviorally identical to the in-editor dock. |
 | `remove-plugin [path]` | Disable the `godot_mcp` addon in `project.godot` `[editor_plugins]` (does not delete the addon files). |
@@ -164,6 +172,17 @@ The cloud paths carry the `/mcp` hub segment so the request reaches the hub rath
 backend (which serves no `/api/tools/*`). Pass `--url http://localhost:<port>` to target a
 local/self-hosted server explicitly.
 
+`run-tool`, `run-system-tool` and `exec` replace step 6 with the **project's connection mode**, read the way the addon
+reads it (`GODOT_MCP_CONNECTION_MODE`, the project's `.env`, the persisted `user://godot-mcp-config.json`, else Cloud,
+the addon's default). Custom mode uses the local server above. Cloud mode uses the cloud hub with the machine's sign-in
+(no editor is started: only an editor connected to ai-game.dev answers). If this machine has **never** signed in to
+ai-game.dev, the project's local server is used instead, with a warning (an editor started now serves it; nothing is
+persisted). A sign-in that exists but cannot be used (expired, revoked, unreadable) is an error (exit 6,
+`NOT_AUTHENTICATED`): a signed-in machine is never switched to a local server. The same holds for `open`, `tools` and
+`open --headless`: on a Cloud project of a signed-in machine `open --headless` starts no editor and exits 6 (use `open`,
+`run-tool` and `exec`, which go through ai-game.dev). An explicit `--url` / `--token` is used as is; a non-local
+`--url` / `GODOT_MCP_HOST` is called directly by `exec` and refused by `open --headless` (a headless editor is local).
+
 ![divider](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true)
 
 ## `exec`
@@ -178,7 +197,7 @@ godot-cli exec 'Helper.Twice(21)' --include helpers       # .cs files/folders un
 
 The code is plain statements; the last expression is the result. The output is the value (`Type: value`) and,
 under `logs:`, what the code printed (`Console`; `GD.Print` / push_warning / push_error with Godot.NET.Sdk 4.5+). A compile error points
-at the snippet's line (`snippet.cs(2,12)`) and exits 1.
+at the snippet's line (`snippet.cs(2,12)`) and exits 6.
 
 - **A running editor of the project** (yours, with a window, or one `godot-cli` started) is reused and never closed.
   Yours must serve the project's **local** server (dock: Custom mode, server started).
@@ -201,6 +220,105 @@ call that starts the editor. Both files are listed in `<project>/.ai-game-dev/.g
 server's 5-minute `tool-timeout`),
 `--no-build`, `--editor-path`, `--token`, `--raw`.
 
+`run-tool` / `run-system-tool` follow the same policy when the call is refused on a **local** URL of a Godot project:
+they start a headless editor (building C# first unless `--no-build`), then retry. A running editor is reused and never
+closed; `--once` closes the editor afterwards only when this call started it. `--no-start` turns this off, and a cloud
+or remote URL never starts anything. Options: `--editor-path`, `--ready-timeout <ms>`.
+
+## Exit codes and output formats
+
+Exit codes are shared with `unity-mcp-cli` and `unreal-mcp-cli` (`godot-cli commands --format json` lists them):
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Generic or unclassified error; also a run interrupted by Ctrl+C / SIGTERM (the Godot process tree is killed) |
+| 2 | Usage error: unknown command or option, bad flag value or argument, an unknown tool (`NOT_FOUND`) (`--help` / `--version` exit 0) |
+| 6 | The command ran and failed: the tool returned an error, script or compilation errors, no test verdict, refused credentials |
+| 7 | The editor or MCP server is unreachable (also HTTP 502) |
+| 8 | Tests ran and at least one failed (a suite-level setup/teardown failure counts) |
+| 14 | Timeout (also HTTP 408 / 504) |
+| 17 | The server is busy (HTTP 503 / 429); the call was not executed |
+| 18 | The editor is blocked by a modal dialog (reserved: not detectable in a headless Godot) |
+
+`update --check` still exits 2 when something is outdated.
+
+**A tool call that did not succeed** (`run-tool`, `run-system-tool`, `exec`, `rql`, `tools`) maps to the same exit code
+and error code in all three CLIs (the table lives in `@baizor/gamedev-cli-core`; `commands --format json` lists it as
+`errorCodes`). When the MCP server answered, its HTTP status decides, and the envelope error carries it:
+`errors[{code, message, httpStatus}]`.
+
+| Condition | HTTP status | Exit | `errors[].code` |
+|---|---|---|---|
+| Bad arguments: a bad flag, tool arguments the CLI or the server rejected (any 4xx not listed here) | 400 (a 422 `[invalid_params]`) | `2` | `USAGE` |
+| No tool by that name (list them with `tools`), or no project at the path | 404 | `2` | `NOT_FOUND` |
+| No usable credentials, or the server refused them: sign in with `login` | 401, 403 | `6` | `NOT_AUTHENTICATED` |
+| The tool ran and reported an error (`status: "error"`, any 5xx not listed here) | 409, 422, 500 | `6` | `TOOL_FAILED` |
+| The project's code did not build, so no editor was started | — | `6` | `COMPILATION_FAILED` |
+| Connection refused or reset, no engine plugin connected to the server, plugin lost after the call was sent | 502 | `7` | `UNREACHABLE` |
+| No answer in time: `--timeout`, or the server's own tool timeout | 408, 504 | `14` | `TIMEOUT` |
+| Busy and did not run the call (reloading, rate-limited, another CLI call holds the editor); retry later | 503, 429 | `17` | `BUSY` |
+| Anything else (the call was aborted, an unexpected error) | — | `1` | `ERROR` |
+
+`--format text|json|ndjson` (default `text`) is accepted by `run-tool`, `run-system-tool`, `exec`, `status`,
+`wait-for-ready`, `check`, `import`, `test`, `export`, `run-script` and `commands`. `json` prints exactly one
+envelope on stdout:
+
+```json
+{ "success": false, "command": "check", "data": { "...": "..." },
+  "errors": [{ "code": "SCRIPT_ERRORS", "message": "res://player.gd:12: error: Expected expression." }],
+  "warnings": [] }
+```
+
+`ndjson` prints events on stderr, one JSON object per line (`{"type":"progress","command":…,"message":…}`, and every
+other line as `{"type":"log","command":…,"level":"info|error","message":…}`), and the envelope as one line on stdout.
+In both, logs, spinners and headings go to stderr without colour. Error codes: `USAGE`, `TOOL_FAILED`, `UNREACHABLE`,
+`TIMEOUT`, `BUSY`, `AWAITING_INPUT`, `TESTS_FAILED`, `TEST_RUN_ERROR`, `COMPILATION_FAILED`, `SCRIPT_ERRORS`,
+`IMPORT_FAILED`, `PROJECT_OPEN`, `NOT_FOUND`, `EXPORT_FAILED`, `NOT_AUTHENTICATED`, `CLOUD_PROJECT`, `ERROR`. `--raw` keeps working as before.
+
+## Headless commands (`check`, `import`, `test`, `export`, `run-script`)
+
+These run Godot without an editor session and need no MCP server. Godot's exit code is not a verdict in headless mode
+(an `--import` with a GDScript parse error, or an addon that fails to load, still exits 0), so each command judges the
+run from its log (`SCRIPT ERROR`, `ERROR:`, `Parse Error`), a marker that proves the step ran, and the files it must
+produce. Each process gets a hard `--timeout` (the whole Godot process tree is killed: exit 14). Logs and scratch
+scripts go to `<project>/.godot/godot-cli/`. `check`, `import`, `test` and `export` refuse a project that is open in an
+editor (exit 6, `PROJECT_OPEN`: an import fights that editor over `.godot/`); `--allow-open` overrides it, `close`
+stops a `godot-cli` editor. The binary comes from `--editor-path`, `GODOT_BIN`, `PATH` or the usual install folders.
+
+```bash
+godot-cli check                     # 0 clean, 6 SCRIPT_ERRORS / COMPILATION_FAILED, 14 timeout
+godot-cli check --strict            # GDScript and C# compiler warnings fail too
+godot-cli test --format github      # ::error annotations; 0 pass, 8 failures, 6 no verdict / no runner
+godot-cli export "Windows Desktop" build/game.exe
+godot-cli run-script tools/migrate.gd -- --dry-run
+```
+
+- **`check [path] [--strict] [--include-addons]`** runs four separate processes (a single cold
+  `--build-solutions --quit` crashes on C# `[Tool]` plugins): `--headless --import`; `dotnet build` for a C# project
+  (errors as `file(line,col): error CS…`); `--headless --editor --quit`, which must print `[Godot-MCP] plugin loaded`
+  when the addon is enabled; and a GDScript pass that loads every `.gd` under `res://` (`res://addons/` only with
+  `--include-addons`) and reports parse errors as `res://file:line`. `--strict` also fails on GDScript warnings (the
+  project's Warn-level warnings raised to errors in memory, never saved) and C# `CS` warnings. Engine messages (a
+  plugin's runtime warnings, for example) are listed as warnings and never fail the check.
+- **`import [path]`** fails on script errors (`SCRIPT_ERRORS`) and on resources that fail to import (`IMPORT_FAILED`).
+- **`test [path]`** finds GUT (`addons/gut`) or gdUnit4 (`addons/gdUnit4`), imports the project (`--no-import` skips
+  it), and runs the runner's command-line script with a JUnit report (`-gjunit_xml_file`, or gdUnit4 `-rd`; gdUnit4
+  runs with `--ignoreHeadlessMode -c`). Exit 0 when all tests pass, 8 on failures, 6 (`TEST_RUN_ERROR`) when there is
+  no report, no test ran, or a test script failed to load (its tests are missing from the report, so it must not pass),
+  6 (`NOT_FOUND`) with an install hint when no runner is installed. `--runner gut|gdunit4`, `--dir <dir>` (repeatable;
+  default `res://test`, `res://tests`, or GUT's `.gutconfig.json`), `--filter <text>` (test scripts whose file name
+  contains it), `--output <file>` (copy the JUnit XML), `--format text|json|ndjson|github`.
+- **`export <preset> <output> [--debug|--pack]`** checks that `export_presets.cfg` has the preset and that the export
+  templates for the editor's version are installed (unless `--pack` or the preset names its own template), runs
+  `--export-release|--export-debug|--export-pack`, and fails (`EXPORT_FAILED`) unless the output file exists, is not
+  empty and was written by this run, and the log has no export errors (Godot writes the executable and exits 0 even
+  when, say, the C# publish failed for want of a `.sln`).
+- **`run-script <script> [args...]`** runs `godot --headless --path <project> -s <script> -- <args>`: the script
+  extends `SceneTree` or `MainLoop` and ends with `quit(code)`. Exit 0 for `quit(0)`; 6 for another code
+  (`data.scriptExitCode`) or a script that failed to load; 14 on `--timeout` (default 300000 ms). It does not import,
+  so it also runs while an editor has the project open.
+
 ## `login`
 
 `godot-cli login` authenticates the editor plugin's **cloud** connection to
@@ -250,17 +368,19 @@ godot-cli setup-skills cursor ./MyGame        # generate into MyGame/.cursor/ski
 godot-cli setup-skills --list                 # list agents + their skills paths
 ```
 
-The command writes a `SKILL.md`-per-tool-family directory (a `godot-mcp/` overview plus one per family:
-`godot-mcp-node`, `godot-mcp-scene`, `godot-mcp-resource`, …) describing the `godot_mcp` addon's tool
-families. It is **idempotent** — re-running rewrites the same bytes.
+It writes, offline (no editor, no server, no network):
 
-Unlike the Unity CLI — which POSTs to a running editor's `/api/system-tools/unity-skill-generate`
-endpoint — the Godot CLI generates the files **locally** from a built-in catalog, so no server and no
-running editor are required. (The addon now *also* exposes `godot-skill-generate` on
-`/api/system-tools/`, but that path needs a booted editor; local generation is the server-less one.) (The addon
-*additionally* auto-generates skills in-process on plugin boot via
-`GodotMcpConnection.Start` → `GenerateSkillFilesIfNeeded`; the CLI command is the
-server-less, scriptable path that does not need a live editor.)
+- `godot-cli/SKILL.md`: how an agent uses this CLI from a cold start: the first editor command starts a headless
+  editor, `rql` with recipes for scenes, nodes and resources, `check` / `test`, `--format json`, what each exit
+  code means. It is short on purpose (an agent keeps every byte it reads in context); `references/rql.md` and
+  `references/install.md` hold the depth, read only when needed. The recipes come from the same source as
+  `godot-cli --help` and `rql --help`, so the skill and the help cannot drift apart.
+- `ai-game-dev-app/SKILL.md`: the companion app, for creative tools the CLI does not have.
+
+It is **idempotent**: re-running rewrites the same bytes. It removes the `godot-mcp` / `godot-mcp-<family>` skills
+earlier versions generated from a hand-written catalog. Per-tool skills are the addon's job: it generates them from
+the tools it really registers whenever the editor runs (toggle in the addon's Skills panel), together with its
+`godot-cli-install` guide.
 
 ## `install-plugin`
 
@@ -333,6 +453,9 @@ import { openProject, runTool, setupMcp, installPlugin, installExtension, execCo
 // The shared extension catalog + lookup helpers are exported too, so a GUI (the app)
 // can render the same list the dock + CLI install from:
 import { EXTENSIONS_CATALOG, findExtension } from 'godot-cli';
+
+// The headless commands, their log/JUnit parsers and the exit codes:
+import { checkProject, importProject, runTests, exportProject, runScript, parseGodotLog, parseJUnit, ExitCode } from 'godot-cli';
 ```
 
 Every function returns a discriminated union (`{ kind: 'success', ... }` / `{ kind: 'failure', error }`)

package/dist/cli.d.ts

@@ -12,3 +12,10 @@ export { closeCommand } from './commands/close.js';
 export { createUpdateCommand } from './commands/update.js';
 export { installPluginCommand } from './commands/install-plugin.js';
 export { removePluginCommand } from './commands/remove-plugin.js';
+export { checkCommand } from './commands/check.js';
+export { importCommand } from './commands/import.js';
+export { testCommand } from './commands/test.js';
+export { exportCommand } from './commands/export.js';
+export { runScriptCommand } from './commands/run-script.js';
+export { createCommandsCommand } from './commands/commands.js';
+export { toolsCommand } from './commands/tools.js';

package/dist/cli.js

@@ -17,4 +17,11 @@ export { closeCommand } from './commands/close.js';
 export { createUpdateCommand } from './commands/update.js';
 export { installPluginCommand } from './commands/install-plugin.js';
 export { removePluginCommand } from './commands/remove-plugin.js';
+export { checkCommand } from './commands/check.js';
+export { importCommand } from './commands/import.js';
+export { testCommand } from './commands/test.js';
+export { exportCommand } from './commands/export.js';
+export { runScriptCommand } from './commands/run-script.js';
+export { createCommandsCommand } from './commands/commands.js';
+export { toolsCommand } from './commands/tools.js';
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,uBAAuB;AAEvB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,uBAAuB;AAEvB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/commands/check.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const checkCommand: Command;

package/dist/commands/check.js

@@ -0,0 +1,48 @@
+import { Command } from 'commander';
+import * as ui from '../utils/ui.js';
+import { CommandOutput, addFormatOption, parseFormat } from '../utils/output.js';
+import { checkProject, failingDiagnostics } from '../lib/check.js';
+import { addHeadlessOptions, diagnosticErrors, finishHeadless, headlessProjectPath, headlessTimeout, printDiagnostics, printSteps, } from './headless-common.js';
+export const checkCommand = addFormatOption(addHeadlessOptions(new Command('check')
+    .description('CI gate without an editor: import, C# build, editor boot and a GDScript load check, judged from the logs')
+    .argument('[path]', 'Godot project path')
+    .option('--strict', 'Fail on GDScript and C# compiler warnings too')
+    .option('--include-addons', 'Also load the GDScript under res://addons/'), 900000)).action(async (positional, options) => {
+    const output = new CommandOutput('check', parseFormat(options.format));
+    const timeoutMs = headlessTimeout(options);
+    const result = await checkProject({
+        projectPath: headlessProjectPath(positional, options),
+        timeoutMs,
+        strict: options.strict === true,
+        includeAddons: options.includeAddons === true,
+        allowOpenProject: options.allowOpen === true,
+        ...(options.editorPath ? { editorPath: options.editorPath } : {}),
+        onProgress: (m) => output.progress(m),
+    });
+    const diagnostics = result.diagnostics ?? [];
+    const failing = failingDiagnostics(diagnostics, options.strict === true);
+    for (const m of result.engineMessages ?? [])
+        output.warnings.push(`engine ${m.severity}: ${m.message}`);
+    for (const d of diagnostics.filter((x) => x.severity === 'warning' && !options.strict))
+        output.warnings.push(`${d.file ?? ''}${d.line ? `:${d.line}` : ''} ${d.message}`.trim());
+    if (!output.machine) {
+        ui.heading('Godot Check');
+        if (result.projectPath)
+            ui.label('Project', result.projectPath);
+        printSteps(result.steps ?? []);
+        printDiagnostics(diagnostics);
+    }
+    const data = result.kind === 'failure' && result.steps === undefined ? null : {
+        projectPath: result.projectPath,
+        addon: result.addon,
+        gdscript: result.gdscript,
+        csharp: result.csharp,
+        diagnostics,
+        steps: result.steps,
+    };
+    const errors = result.kind === 'failure'
+        ? diagnosticErrors((d) => (d.source === 'csharp' ? 'COMPILATION_FAILED' : 'SCRIPT_ERRORS'), failing)
+        : [];
+    finishHeadless(output, result, data, errors, 'No script or compilation errors');
+});
+//# sourceMappingURL=check.js.map

package/dist/commands/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"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"}

package/dist/commands/close.d.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 export interface CloseOptions {
+    path?: string;
     timeout?: string;
     force?: boolean;
     ownedOnly?: boolean;
@@ -18,4 +19,6 @@ export declare function isGodotProjectRoot(projectPath: string): boolean;
 export declare function parseTimeoutSeconds(raw: string | undefined): number | null;
 /** Resolve the editor PID for a given project path, or null when not running. */
 export declare function resolveEditorPid(projectPath: string): number | null;
+/** Whether a command line runs Godot's `_console` build: a windowless wrapper whose child is the editor. */
+export declare function isConsoleWrapper(commandLine: string): boolean;
 export declare const closeCommand: Command;