# Referencia de godot-cli — Godot · AI Game Developer Wiki

Todos los comandos y flags de godot-cli para Godot MCP, desde install-plugin, login y setup-mcp hasta open, exec, run-tool, configure e install-extension.

Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/godot/cli).

`godot-cli` es la herramienta de línea de comandos para Godot MCP, publicada en npm. Instala el addon, inicia tu sesión, escribe las configuraciones de los agentes de IA, compila y abre el editor con los ajustes de conexión correctos, y llama a herramientas desde scripts. Esta página enumera todos los comandos de `godot-cli` 0.34.0 con sus flags.

## Instalación y conceptos básicos

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

Requiere Node.js `^20.19.0` o `>=22.12.0` y funciona en Windows, macOS y Linux. También puedes ejecutar cualquier comando sin instalarlo: `npx godot-cli <command>`.

La mayoría de los comandos aceptan la carpeta del proyecto como un `[path]` posicional opcional (o `--path <path>`) y usan por defecto la carpeta actual. Todos los comandos aceptan `-v` / `--verbose` para obtener salida de diagnóstico.

## Resumen de comandos

| Comando | Qué hace |
| --- | --- |
| `install-plugin [path]` | Instala el addon, modifica el `.csproj` y habilita el plugin. |
| `install-extension <id> [path]` | Añade o actualiza un paquete de extensión en el `.csproj`. |
| `remove-plugin [path]` | Deshabilita el addon en `project.godot` (los archivos se conservan). |
| `create-project [path]` | Genera la estructura de un proyecto mínimo de Godot 4. |
| `build [path]` | Compila el ensamblado C# del proyecto. |
| `open [path]` | Compila y, después, abre el editor de Godot con los ajustes de conexión. |
| `close [path]` | Detiene el editor de Godot que está en ejecución para el proyecto. |
| `exec [code]` | Ejecuta C# en el editor mediante `script-execute`. |
| `login [path]` | Inicia sesión en ai-game.dev con el flujo de dispositivo. |
| `setup-mcp <agent> [path]` | Escribe la configuración MCP de un agente de IA. |
| `setup-skills <agent> [path]` | Genera archivos de skills para un agente de IA. |
| `configure [path]` | Muestra u oculta herramientas, prompts y recursos. |
| `run-tool <tool> [path]` | Llama a una herramienta MCP por HTTP. |
| `run-system-tool <tool> [path]` | Llama a una herramienta del sistema por HTTP. |
| `status [path]` | Comprueba el editor y el servidor MCP. |
| `wait-for-ready [path]` | Espera hasta que el editor responda a `ping`. |
| `update` | Actualiza `godot-cli` en sí. |

## install-plugin

Instala el addon `godot_mcp` de principio a fin: descarga la versión del addon desde GitHub (o copia una local), añade las `PackageReference` de NuGet y el `<EmbeddedResource>` del catálogo de extensiones al `.csproj`, establece `EnableDynamicLoading` y habilita el plugin en `project.godot`. Se puede volver a ejecutar sin problema.

| Flag | Significado |
| --- | --- |
| `--source <path>` | Copia el addon desde una carpeta local en lugar de descargarlo (sin conexión, desarrollo, CI). |
| `--version <x.y.z>` | Versión del addon que se descargará. Por defecto, la versión de la CLI. Se ignora con `--source`. |
| `--with-server` | También descarga el binario `gamedev-mcp-server` correspondiente, verificado con las sumas de comprobación de la versión. |
| `--server-source <path>` | Instala el servidor desde una carpeta local o un `.zip`. Implica `--with-server`. |
| `--server-version <x.y.z>` | Versión del servidor que se descargará. Por defecto, la versión del servidor fijada por el addon. |
| `--enroll <code>` | Canjea un código de enrolamiento de agente (inicia sesión en el plugin sin navegador). |
| `--enroll-stdin` | Lee el código de enrolamiento desde stdin, para que no quede en el historial del shell. |
| `--base-url <url>` | URL de la nube contra la que se canjea el código de enrolamiento. Por defecto `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]` resuelve el id (id de paquete o nombre) en el catálogo de extensiones y añade o actualiza su `<PackageReference>`. `--version <x.y.z>` solicita una versión exacta en lugar de la última estable. Ejecuta `godot-cli build` después. Consulta [Extensions](https://ai-game.dev/es/docs/wiki/godot/extensions).

## remove-plugin

Deshabilita el addon en la sección `[editor_plugins]` de `project.godot`. No elimina `addons/godot_mcp/` ni las entradas del `.csproj`.

## create-project

Genera la estructura de un proyecto mínimo de Godot 4 (`project.godot` e `icon.svg`). Se niega a sobrescribir un proyecto existente de Godot, Unity o Unreal.

| Flag | Significado |
| --- | --- |
| `--dotnet` | También crea un `.csproj` de C# con `Godot.NET.Sdk` (necesario para Godot MCP). |
| `--name <name>` | Nombre del proyecto. Por defecto, el nombre de la carpeta. |

## build

Ejecuta `dotnet build` en el `.csproj` del proyecto para que el addon se cargue la próxima vez que se abra el editor. Los proyectos sin `.csproj` se omiten.

| Flag | Significado |
| --- | --- |
| `--configuration <cfg>` | Configuración de MSBuild. Por defecto `Debug`. |
| `--dotnet-path <path>` | Usa este ejecutable `dotnet` en lugar del que está en `PATH`. |

## open

Compila el ensamblado C# , localiza el editor de Godot y abre el proyecto. Si la compilación falla, el editor no se inicia. El editor se busca en este orden: `--editor-path`, la variable de entorno `GODOT_BIN` o `GODOT4_BIN`, un binario de Godot en `PATH` (en Windows se prefiere la compilación .NET) y, por último, las carpetas de instalación habituales.

| Flag | Significado |
| --- | --- |
| `--editor-path <path>` | Ejecutable del editor de Godot que se usará. |
| `--no-build` | Omite la compilación de C#. |
| `--build-configuration <cfg>` | Configuración para la compilación de preapertura. Por defecto, `Debug`. |
| `--no-connect` | Abrir sin ninguna variable de conexión `GODOT_MCP_*`. |
| `--mode <Cloud or Custom>` | Establece `GODOT_MCP_CONNECTION_MODE`. |
| `--url <url>` | Establece `GODOT_MCP_HOST`. |
| `--cloud-url <url>` | Establece `GODOT_MCP_CLOUD_URL`. |
| `--token <token>` | Establece `GODOT_MCP_TOKEN`. |
| `--auth <None or Required>` | Establece `GODOT_MCP_AUTH_OPTION`. |
| `--log-level <level>` | Establece `GODOT_MCP_LOG_LEVEL` (`Trace`, `Debug`, `Info`, `Warning`, `Error`, `None`). |
| `--headless` | Inicia un editor sin ventana en el servidor local del proyecto y espera hasta que esté listo. Reutiliza uno que ya se esté ejecutando. |
| `--idle-timeout <seconds>` | Con `--headless`: salir tras este número de segundos sin llamadas a herramientas (`0` = nunca). |
| `--ready-timeout <ms>` | Con `--headless`: cuánto tiempo esperar a que el editor esté listo. |

## close

Detiene de forma ordenada el editor de Godot que se ejecuta para el proyecto.

| Opción | Significado |
| --- | --- |
| `--timeout <seconds>` | Cuánto tiempo esperar a un cierre ordenado. Por defecto, 30. |
| `--force` | Finalizar el proceso del editor si no se cierra a tiempo. |
| `--owned-only` | Cerrar solo un editor que haya iniciado `godot-cli` (`exec`, `open --headless`), nunca el tuyo. Primero guarda las escenas abiertas. |
| `--token <token>` | Con `--owned-only`: token bearer. Por defecto, `GODOT_MCP_TOKEN`. |

## exec

Ejecuta C# en el editor del proyecto con la herramienta `script-execute`. El código son sentencias simples; la última expresión es el resultado. Si hay un editor del proyecto en ejecución, se reutiliza (el tuyo debe estar en modo Custom con su servidor local iniciado). En caso contrario, `exec` compila el proyecto e inicia un editor headless conectado a un servidor local, que se cierra tras `--idle` segundos sin llamadas (por defecto, 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
```

| Opción | Significado |
| --- | --- |
| `--path <path>` | Carpeta del proyecto. |
| `-f, --file <file>` | Leer el código desde un archivo (`-` para stdin). |
| `--using <namespace>` | Espacio de nombres adicional. Se puede repetir. |
| `--include <path>` | Archivo o carpeta `.cs` de ayuda bajo `<project>/.ai-game-dev/snippets`. Se puede repetir. |
| `--window` | Iniciar el editor con ventana en lugar de headless. |
| `--idle <seconds>` | Tiempo de inactividad antes de que se cierre un editor iniciado (`0` = nunca). |
| `--ready-timeout <ms>` | Cuánto tiempo esperar a un editor iniciado. |
| `--timeout <ms>` | Tiempo de espera de la llamada a la herramienta. Por defecto, 310000. |
| `--no-build` | No compilar antes de iniciar un editor. |
| `--editor-path <path>` | Ejecutable del editor de Godot. |
| `--url <url>` | URL del servidor MCP local. Por defecto: el puerto local del proyecto. |
| `--token <token>` | Token bearer. Por defecto, `GODOT_MCP_TOKEN`. |
| `--raw` | Imprime el JSON de respuesta sin procesar de la herramienta. |

Un error de compilación señala la línea del snippet y sale con código 1.

## login

Inicia sesión en ai-game.dev con el flujo de dispositivo OAuth 2.1 y guarda la credencial en `~/.ai-game-dev/credentials.json`, que el editor recoge. Consulta [Conectar clientes de IA](https://ai-game.dev/es/docs/wiki/godot/connecting-ai-clients#device-flow).

| Opción | Significado |
| --- | --- |
| `--project <path>` | Guardar en su lugar una credencial por proyecto en `<path>/.ai-game-dev/`. |
| `--base-url <url>` | Iniciar sesión contra otro servidor. Por defecto, `https://ai-game.dev`. |
| `--force` | Iniciar sesión de nuevo aunque ya exista una credencial. |
| `--tools-only` | Modo CI: crear una credencial solo para herramientas que la aplicación de escritorio no recoge. |
| `--yes` | Reemplazar la credencial de otra cuenta sin preguntar. |

## setup-mcp

`godot-cli setup-mcp <agent> [path]` escribe la configuración MCP del agente, fijada a este proyecto por defecto. Los ids de agente y los archivos de configuración se enumeran en [Conectar clientes de IA](https://ai-game.dev/es/docs/wiki/godot/connecting-ai-clients#agents).

| Opción | Significado |
| --- | --- |
| `--list` | Enumera todos los ids de agente. |
| `--url <url>` | Sustitución del host del servidor, por ejemplo, un servidor local. |
| `--token <token>` | Sustitución del token. Por defecto, `GODOT_MCP_TOKEN`. |
| `--no-pin` | Escribir la URL `/mcp` simple en lugar de la fijada. |
| `--oauth` | Nube: configuración solo de URL; el agente inicia sesión con su propio OAuth. |
| `--regenerate-key` | Nube: crear una nueva clave de proyecto y revocar la anterior. |

## setup-skills

`godot-cli setup-skills <agent> [path]` escribe archivos `SKILL.md` para las familias de herramientas del addon en la carpeta de skills del agente (por ejemplo, `.claude/skills`). No necesita un editor en ejecución. `--list` muestra la compatibilidad de skills de cada agente.

## configure

Enumera o cambia qué herramientas, prompts y recursos ven los clientes MCP, en `.godot-mcp/features.json`. Los elementos ocultos siguen ejecutándose cuando se llaman por nombre.

| Opción | Significado |
| --- | --- |
| `--list` | Mostrar la configuración actual. |
| `--enable-tools <names>` / `--disable-tools <names>` | Mostrar u ocultar herramientas (separadas por comas). |
| `--enable-all-tools` / `--disable-all-tools` | Mostrar u ocultar todas las herramientas. |
| `--enable-prompts <names>` / `--disable-prompts <names>` | Mostrar u ocultar prompts. |
| `--enable-all-prompts` / `--disable-all-prompts` | Mostrar u ocultar todos los prompts. |
| `--enable-resources <names>` / `--disable-resources <names>` | Mostrar u ocultar recursos. |
| `--enable-all-resources` / `--disable-all-resources` | Mostrar u ocultar todos los recursos. |
| `--agent <id>` | Configura un agente mediante el binario del servidor gestionado (requiere `install-plugin --with-server`). |
| `--url <url>` | Con `--agent`: sobrescribe la URL del servidor. |

## run-tool y run-system-tool

Llama a una herramienta directamente a través de la API HTTP del servidor: `run-tool` envía una petición POST a `/api/tools/<tool>` y `run-system-tool` a `/api/system-tools/<tool>` (herramientas ocultas para los clientes MCP, como `ping`).

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

| Opción | Significado |
| --- | --- |
| `--url <url>` | URL base del servidor. |
| `--token <token>` | Token Bearer. Por defecto, `GODOT_MCP_TOKEN`. |
| `--input <json>` | Argumentos de la herramienta como cadena JSON. |
| `--input-file <file>` | Lee los argumentos JSON desde un archivo. |
| `--raw` | Imprime el JSON sin procesar. |
| `--timeout <ms>` | Tiempo de espera de la petición. Por defecto, 60000. |

Sin `--url`, el servidor se elige a partir de `GODOT_MCP_HOST`, luego de `GODOT_MCP_CLOUD_URL`, después la nube cuando `GODOT_MCP_CONNECTION_MODE=Cloud`, luego el servidor inscrito del proyecto y, por último, el puerto local del proyecto.

## status y wait-for-ready

`status` detecta un editor en ejecución para el proyecto y sondea el servidor (`--url`, `--token`, `--timeout <ms>`, por defecto 5000). `wait-for-ready` consulta `ping` repetidamente hasta que el editor responde (`--url`, `--token`, `--timeout <ms>`, por defecto 120000; `--interval <ms>`, por defecto 3000). Úsalo en scripts después de `open`.

## update

`godot-cli update` busca en npm una versión más reciente de `godot-cli` y la instala; `--check` solo informa.

## Relacionado

- La aplicación AI Game Dev tiene su propia CLI `gamedev`: [App CLI](https://ai-game.dev/es/docs/wiki/app/cli).
- Unity y Unreal tienen `unity-mcp-cli` y `unreal-mcp-cli`: consulta las wikis de [Unity MCP](https://ai-game.dev/es/docs/wiki/unity) y [Unreal MCP](https://ai-game.dev/es/docs/wiki/unreal).

---

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

Machine-translated (es) from the English page: https://ai-game.dev/docs/wiki/godot/cli