# godot-cli reference

Every godot-cli command and flag for Godot MCP, from install-plugin, login and setup-mcp to open, exec, run-tool, configure and install-extension.

_Last updated: 2026-11-04_

`godot-cli` is the command-line tool for Godot MCP, published on npm. It installs the addon, signs you in, writes AI agent configs, builds and opens the editor with the right connection settings, and calls tools from scripts. This page lists every command in `godot-cli` 0.34.0 with its flags.

## Install and basics

```bash
npm install -g godot-cli
godot-cli --help
godot-cli <command> --help
```

It needs Node.js `^20.19.0` or `>=22.12.0` and runs on Windows, macOS and Linux. You can also run any command without installing: `npx godot-cli <command>`.

Most commands take the project folder as an optional positional `[path]` (or `--path <path>`) and default to the current folder. Every command accepts `-v` / `--verbose` for diagnostic output.

## Command overview

| Command | What it does |
| --- | --- |
| `install-plugin [path]` | Install the addon, patch the `.csproj`, enable the plugin. |
| `install-extension <id> [path]` | Add or update an extension package in the `.csproj`. |
| `remove-plugin [path]` | Disable the addon in `project.godot` (files stay). |
| `create-project [path]` | Scaffold a minimal Godot 4 project. |
| `build [path]` | Build the project's C# assembly. |
| `open [path]` | Build, then open the Godot editor with connection settings. |
| `close [path]` | Stop the Godot editor running for the project. |
| `exec [code]` | Run C# in the editor through `script-execute`. |
| `login [path]` | Sign in to ai-game.dev with the device flow. |
| `setup-mcp <agent> [path]` | Write an AI agent's MCP config. |
| `setup-skills <agent> [path]` | Generate skill files for an AI agent. |
| `configure [path]` | Show or hide tools, prompts and resources. |
| `run-tool <tool> [path]` | Call an MCP tool over HTTP. |
| `run-system-tool <tool> [path]` | Call a system tool over HTTP. |
| `status [path]` | Check the editor and the MCP server. |
| `wait-for-ready [path]` | Wait until the editor answers `ping`. |
| `update` | Update `godot-cli` itself. |

## install-plugin

Installs the `godot_mcp` addon end to end: downloads the addon release from GitHub (or copies a local one), adds the NuGet `PackageReference`s and the extension catalog `<EmbeddedResource>` to the `.csproj`, sets `EnableDynamicLoading`, and enables the plugin in `project.godot`. Safe to rerun.

| Flag | Meaning |
| --- | --- |
| `--source <path>` | Copy the addon from a local folder instead of downloading (offline, development, CI). |
| `--version <x.y.z>` | Addon release to download. Defaults to the CLI's version. Ignored with `--source`. |
| `--with-server` | Also download the matching `gamedev-mcp-server` binary, checked against the release checksums. |
| `--server-source <path>` | Install the server from a local folder or `.zip`. Implies `--with-server`. |
| `--server-version <x.y.z>` | Server version to download. Defaults to the addon's pinned server version. |
| `--enroll <code>` | Redeem an agent enrollment code (signs the plugin in without a browser). |
| `--enroll-stdin` | Read the enrollment code from stdin, so it stays out of shell history. |
| `--base-url <url>` | Cloud URL to redeem the enrollment code against. Default `https://ai-game.dev`. |

```bash
godot-cli install-plugin ./MyGodotProject
godot-cli install-plugin --version 0.34.0 ./MyGodotProject
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProject
```

## install-extension

`godot-cli install-extension <id> [path]` resolves the id (package id or name) in the extension catalog and adds or updates its `<PackageReference>`. `--version <x.y.z>` requests an exact version instead of the latest stable one. Run `godot-cli build` afterwards. See [Extensions](https://ai-game.dev/docs/wiki/godot/extensions).

## remove-plugin

Disables the addon in the `[editor_plugins]` section of `project.godot`. It does not delete `addons/godot_mcp/` or the `.csproj` entries.

## create-project

Scaffolds a minimal Godot 4 project (`project.godot` and `icon.svg`). It refuses to overwrite an existing Godot, Unity or Unreal project.

| Flag | Meaning |
| --- | --- |
| `--dotnet` | Also create a `Godot.NET.Sdk` C# `.csproj` (needed for Godot MCP). |
| `--name <name>` | Project name. Defaults to the folder name. |

## build

Runs `dotnet build` on the project's `.csproj` so the addon loads on the next editor open. Projects without a `.csproj` are skipped.

| Flag | Meaning |
| --- | --- |
| `--configuration <cfg>` | MSBuild configuration. Default `Debug`. |
| `--dotnet-path <path>` | Use this `dotnet` executable instead of the one on `PATH`. |

## open

Builds the C# assembly, finds the Godot editor and opens the project. If the build fails, the editor is not started. The editor is found in this order: `--editor-path`, the `GODOT_BIN` or `GODOT4_BIN` environment variable, a Godot binary on `PATH` (the .NET build is preferred on Windows), then common install folders.

| Flag | Meaning |
| --- | --- |
| `--editor-path <path>` | Godot editor executable to use. |
| `--no-build` | Skip the C# build. |
| `--build-configuration <cfg>` | Configuration for the pre-open build. Default `Debug`. |
| `--no-connect` | Open without any `GODOT_MCP_*` connection variables. |
| `--mode <Cloud or Custom>` | Sets `GODOT_MCP_CONNECTION_MODE`. |
| `--url <url>` | Sets `GODOT_MCP_HOST`. |
| `--cloud-url <url>` | Sets `GODOT_MCP_CLOUD_URL`. |
| `--token <token>` | Sets `GODOT_MCP_TOKEN`. |
| `--auth <None or Required>` | Sets `GODOT_MCP_AUTH_OPTION`. |
| `--log-level <level>` | Sets `GODOT_MCP_LOG_LEVEL` (`Trace`, `Debug`, `Info`, `Warning`, `Error`, `None`). |
| `--headless` | Start a windowless editor on the project's local server and wait until it is ready. Reuses a running one. |
| `--idle-timeout <seconds>` | With `--headless`: quit after this many seconds without tool calls (`0` = never). |
| `--ready-timeout <ms>` | With `--headless`: how long to wait for the editor to become ready. |

## close

Gracefully stops the Godot editor running for the project.

| Flag | Meaning |
| --- | --- |
| `--timeout <seconds>` | How long to wait for a polite quit. Default 30. |
| `--force` | Kill the editor if it does not exit in time. |
| `--owned-only` | Close only an editor that `godot-cli` started (`exec`, `open --headless`), never yours. It saves open scenes first. |
| `--token <token>` | With `--owned-only`: bearer token. Default `GODOT_MCP_TOKEN`. |

## exec

Runs C# in the project's editor with the `script-execute` tool. The code is plain statements; the last expression is the result. If an editor of the project is running, it is reused (yours must be in Custom mode with its local server started). Otherwise `exec` builds the project and starts a headless editor connected to a local server, which quits after `--idle` seconds without calls (default 300).

```bash
godot-cli exec '1 + 2' --path ./MyGodotProject
godot-cli exec -f snippet.cs --using MyGame.Gameplay
godot-cli exec 'Helper.Twice(21)' --include helpers
```

| Flag | Meaning |
| --- | --- |
| `--path <path>` | Project folder. |
| `-f, --file <file>` | Read the code from a file (`-` for stdin). |
| `--using <namespace>` | Extra namespace. Repeatable. |
| `--include <path>` | Helper `.cs` file or folder under `<project>/.ai-game-dev/snippets`. Repeatable. |
| `--window` | Start the editor with a window instead of headless. |
| `--idle <seconds>` | Idle time before a started editor quits (`0` = never). |
| `--ready-timeout <ms>` | How long to wait for a started editor. |
| `--timeout <ms>` | Tool call timeout. Default 310000. |
| `--no-build` | Do not build before starting an editor. |
| `--editor-path <path>` | Godot editor executable. |
| `--url <url>` | Local MCP server URL. Default: the project's local port. |
| `--token <token>` | Bearer token. Default `GODOT_MCP_TOKEN`. |
| `--raw` | Print the raw tool response JSON. |

A compile error points at the snippet line and exits with code 1.

## login

Signs in to ai-game.dev with the OAuth 2.1 device flow and saves the credential to `~/.ai-game-dev/credentials.json`, which the editor picks up. See [Connecting AI clients](https://ai-game.dev/docs/wiki/godot/connecting-ai-clients#device-flow).

| Flag | Meaning |
| --- | --- |
| `--project <path>` | Save a per-project credential under `<path>/.ai-game-dev/` instead. |
| `--base-url <url>` | Sign in against another server. Default `https://ai-game.dev`. |
| `--force` | Sign in again even if a credential exists. |
| `--tools-only` | CI mode: create a tools-only credential that the desktop app does not pick up. |
| `--yes` | Replace another account's credential without asking. |

## setup-mcp

`godot-cli setup-mcp <agent> [path]` writes the agent's MCP config, pinned to this project by default. The agent ids and config files are listed on [Connecting AI clients](https://ai-game.dev/docs/wiki/godot/connecting-ai-clients#agents).

| Flag | Meaning |
| --- | --- |
| `--list` | List all agent ids. |
| `--url <url>` | Server host override, for example a local server. |
| `--token <token>` | Token override. Default `GODOT_MCP_TOKEN`. |
| `--no-pin` | Write the plain `/mcp` URL instead of the pinned one. |
| `--oauth` | Cloud: URL-only config; the agent signs in with its own OAuth. |
| `--regenerate-key` | Cloud: create a new project key and revoke the old one. |

## setup-skills

`godot-cli setup-skills <agent> [path]` writes `SKILL.md` files for the addon's tool families into the agent's skills folder (for example `.claude/skills`). It needs no running editor. `--list` shows each agent's skills support.

## configure

Lists or changes which tools, prompts and resources MCP clients see, in `.godot-mcp/features.json`. Hidden items still run when called by name.

| Flag | Meaning |
| --- | --- |
| `--list` | Show the current configuration. |
| `--enable-tools <names>` / `--disable-tools <names>` | Show or hide tools (comma-separated). |
| `--enable-all-tools` / `--disable-all-tools` | Show or hide all tools. |
| `--enable-prompts <names>` / `--disable-prompts <names>` | Show or hide prompts. |
| `--enable-all-prompts` / `--disable-all-prompts` | Show or hide all prompts. |
| `--enable-resources <names>` / `--disable-resources <names>` | Show or hide resources. |
| `--enable-all-resources` / `--disable-all-resources` | Show or hide all resources. |
| `--agent <id>` | Configure an agent through the managed server binary (needs `install-plugin --with-server`). |
| `--url <url>` | With `--agent`: server URL override. |

## run-tool and run-system-tool

Call a tool directly over the server's HTTP API: `run-tool` posts to `/api/tools/<tool>`, `run-system-tool` to `/api/system-tools/<tool>` (tools hidden from MCP clients, such as `ping`).

```bash
godot-cli run-tool rql-query ./MyGodotProject --input '{"query":"nodes | select name class"}'
godot-cli run-system-tool ping ./MyGodotProject
```

| Flag | Meaning |
| --- | --- |
| `--url <url>` | Server base URL. |
| `--token <token>` | Bearer token. Default `GODOT_MCP_TOKEN`. |
| `--input <json>` | Tool arguments as a JSON string. |
| `--input-file <file>` | Read the JSON arguments from a file. |
| `--raw` | Print raw JSON. |
| `--timeout <ms>` | Request timeout. Default 60000. |

Without `--url`, the server is chosen from `GODOT_MCP_HOST`, then `GODOT_MCP_CLOUD_URL`, then the cloud when `GODOT_MCP_CONNECTION_MODE=Cloud`, then the project's enrolled server, and finally the project's local port.

## status and wait-for-ready

`status` detects a running editor for the project and probes the server (`--url`, `--token`, `--timeout <ms>`, default 5000). `wait-for-ready` polls `ping` until the editor answers (`--url`, `--token`, `--timeout <ms>` default 120000, `--interval <ms>` default 3000). Use it in scripts after `open`.

## update

`godot-cli update` checks npm for a newer `godot-cli` and installs it; `--check` only reports.

## Related

- The AI Game Dev app has its own `gamedev` CLI: [App CLI](https://ai-game.dev/docs/wiki/app/cli).
- Unity and Unreal have `unity-mcp-cli` and `unreal-mcp-cli`: see the [Unity MCP](https://ai-game.dev/docs/wiki/unity) and [Unreal MCP](https://ai-game.dev/docs/wiki/unreal) wikis.

---

Source (HTML): https://ai-game.dev/docs/wiki/godot/cli