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.
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
npm install -g godot-cli
godot-cli --help
godot-cli <command> --helpIt 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 PackageReferences 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. |
godot-cli install-plugin ./MyGodotProject
godot-cli install-plugin --version 0.34.0 ./MyGodotProject
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProjectinstall-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.
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).
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.
| 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.
| 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).
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
gamedevCLI: App CLI. - Unity and Unreal have
unity-mcp-cliandunreal-mcp-cli: see the Unity MCP and Unreal MCP wikis.