Referência do godot-cli
Todos os comandos e flags do godot-cli para o Godot MCP, de install-plugin, login e setup-mcp a open, exec, run-tool, configure e install-extension.
godot-cli é a ferramenta de linha de comando para o Godot MCP, publicada no npm. Ela instala o addon, faz seu login, grava as configurações dos agentes de IA, compila e abre o editor com as configurações de conexão corretas, e chama ferramentas a partir de scripts. Esta página lista todos os comandos do godot-cli 0.34.0 com suas flags.
Instalação e noções básicas
npm install -g godot-cli
godot-cli --help
godot-cli <command> --helpRequer Node.js ^20.19.0 ou >=22.12.0 e funciona no Windows, macOS e Linux. Você também pode executar qualquer comando sem instalar: npx godot-cli <command>.
A maioria dos comandos aceita a pasta do projeto como um [path] posicional opcional (ou --path <path>) e usa a pasta atual por padrão. Todos os comandos aceitam -v / --verbose para saída de diagnóstico.
Visão geral dos comandos
| Comando | O que faz |
|---|---|
install-plugin [path] | Instala o addon, aplica patch no .csproj, habilita o plugin. |
install-extension <id> [path] | Adiciona ou atualiza um pacote de extensão no .csproj. |
remove-plugin [path] | Desabilita o addon no project.godot (os arquivos permanecem). |
create-project [path] | Cria a estrutura de um projeto Godot 4 mínimo. |
build [path] | Compila o assembly C# do projeto. |
open [path] | Compila e depois abre o editor Godot com as configurações de conexão. |
close [path] | Encerra o editor Godot em execução para o projeto. |
exec [code] | Executa C# no editor por meio de script-execute. |
login [path] | Faz login no ai-game.dev com o fluxo de dispositivo. |
setup-mcp <agent> [path] | Grava a configuração MCP de um agente de IA. |
setup-skills <agent> [path] | Gera arquivos de skill para um agente de IA. |
configure [path] | Mostra ou oculta ferramentas, prompts e recursos. |
run-tool <tool> [path] | Chama uma ferramenta MCP via HTTP. |
run-system-tool <tool> [path] | Chama uma ferramenta de sistema via HTTP. |
status [path] | Verifica o editor e o servidor MCP. |
wait-for-ready [path] | Aguarda até o editor responder a ping. |
update | Atualiza o próprio godot-cli. |
install-plugin
Instala o addon godot_mcp de ponta a ponta: baixa a release do addon do GitHub (ou copia uma local), adiciona os PackageReference do NuGet e o <EmbeddedResource> do catálogo de extensões ao .csproj, define EnableDynamicLoading e habilita o plugin no project.godot. Pode ser executado novamente com segurança.
| Flag | Significado |
|---|---|
--source <path> | Copia o addon de uma pasta local em vez de baixar (offline, desenvolvimento, CI). |
--version <x.y.z> | Release do addon a baixar. O padrão é a versão da CLI. Ignorado com --source. |
--with-server | Também baixa o binário gamedev-mcp-server correspondente, verificado com os checksums da release. |
--server-source <path> | Instala o servidor a partir de uma pasta local ou .zip. Implica --with-server. |
--server-version <x.y.z> | Versão do servidor a baixar. O padrão é a versão de servidor fixada pelo addon. |
--enroll <code> | Resgata um código de inscrição de agente (faz login do plugin sem navegador). |
--enroll-stdin | Lê o código de inscrição da entrada padrão, para que ele não fique no histórico do shell. |
--base-url <url> | URL da nuvem usada para resgatar o código de inscrição. Padrão 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] resolve o id (id do pacote ou nome) no catálogo de extensões e adiciona ou atualiza seu <PackageReference>. --version <x.y.z> solicita uma versão exata em vez da última estável. Execute godot-cli build depois. Veja Extensões.
remove-plugin
Desabilita o addon na seção [editor_plugins] do project.godot. Não exclui addons/godot_mcp/ nem as entradas do .csproj.
create-project
Cria a estrutura de um projeto Godot 4 mínimo (project.godot e icon.svg). Recusa-se a sobrescrever um projeto Godot, Unity ou Unreal existente.
| Flag | Significado |
|---|---|
--dotnet | Também cria um .csproj C# do Godot.NET.Sdk (necessário para o Godot MCP). |
--name <name> | Nome do projeto. O padrão é o nome da pasta. |
build
Executa dotnet build no .csproj do projeto para que o addon carregue na próxima abertura do editor. Projetos sem .csproj são ignorados.
| Flag | Significado |
|---|---|
--configuration <cfg> | Configuração do MSBuild. Padrão Debug. |
--dotnet-path <path> | Usa este executável dotnet em vez do que está no PATH. |
open
Compila o assembly C#, localiza o editor Godot e abre o projeto. Se a compilação falhar, o editor não é iniciado. O editor é localizado nesta ordem: --editor-path, a variável de ambiente GODOT_BIN ou GODOT4_BIN, um binário do Godot no PATH (a build .NET é preferida no Windows) e, por fim, as pastas de instalação comuns.
| Flag | Significado |
|---|---|
--editor-path <path> | Executável do editor Godot a usar. |
--no-build | Pula a compilação C#. |
--build-configuration <cfg> | Configuração para o build de pré-abertura. Padrão Debug. |
--no-connect | Abrir sem nenhuma variável de conexão GODOT_MCP_*. |
--mode <Cloud or Custom> | Define GODOT_MCP_CONNECTION_MODE. |
--url <url> | Define GODOT_MCP_HOST. |
--cloud-url <url> | Define GODOT_MCP_CLOUD_URL. |
--token <token> | Define GODOT_MCP_TOKEN. |
--auth <None or Required> | Define GODOT_MCP_AUTH_OPTION. |
--log-level <level> | Define GODOT_MCP_LOG_LEVEL (Trace, Debug, Info, Warning, Error, None). |
--headless | Inicia um editor sem janela no servidor local do projeto e aguarda até que ele esteja pronto. Reutiliza um que já esteja em execução. |
--idle-timeout <seconds> | Com --headless: encerra após esse número de segundos sem chamadas de ferramenta (0 = nunca). |
--ready-timeout <ms> | Com --headless: quanto tempo esperar até o editor ficar pronto. |
close
Encerra de forma graciosa o editor Godot em execução no projeto.
| Flag | Significado |
|---|---|
--timeout <seconds> | Quanto tempo esperar por um encerramento educado. Padrão 30. |
--force | Mata o editor se ele não sair a tempo. |
--owned-only | Fecha apenas um editor iniciado pelo godot-cli (exec, open --headless), nunca o seu. Ele salva as cenas abertas primeiro. |
--token <token> | Com --owned-only: bearer token. Padrão GODOT_MCP_TOKEN. |
exec
Executa C# no editor do projeto com a ferramenta script-execute. O código são comandos simples; a última expressão é o resultado. Se um editor do projeto estiver em execução, ele é reutilizado (o seu deve estar no modo Custom com o servidor local iniciado). Caso contrário, exec compila o projeto e inicia um editor headless conectado a um servidor local, que se encerra após --idle segundos sem chamadas (padrão 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 | Significado |
|---|---|
--path <path> | Pasta do projeto. |
-f, --file <file> | Lê o código de um arquivo (- para stdin). |
--using <namespace> | Namespace extra. Repetível. |
--include <path> | Arquivo ou pasta .cs auxiliar em <project>/.ai-game-dev/snippets. Repetível. |
--window | Inicia o editor com janela em vez de headless. |
--idle <seconds> | Tempo ocioso antes de um editor iniciado se encerrar (0 = nunca). |
--ready-timeout <ms> | Quanto tempo esperar por um editor iniciado. |
--timeout <ms> | Tempo limite da chamada de ferramenta. Padrão 310000. |
--no-build | Não compila antes de iniciar um editor. |
--editor-path <path> | Executável do editor Godot. |
--url <url> | URL do servidor MCP local. Padrão: a porta local do projeto. |
--token <token> | Bearer token. Padrão GODOT_MCP_TOKEN. |
--raw | Imprime o JSON bruto da resposta da ferramenta. |
Um erro de compilação aponta a linha do snippet e sai com código 1.
login
Faz login no ai-game.dev com o fluxo de dispositivo OAuth 2.1 e salva a credencial em ~/.ai-game-dev/credentials.json, que o editor utiliza. Veja Conectando clientes de IA.
| Flag | Significado |
|---|---|
--project <path> | Salva uma credencial por projeto em <path>/.ai-game-dev/ em vez disso. |
--base-url <url> | Faz login em outro servidor. Padrão https://ai-game.dev. |
--force | Faz login novamente mesmo que já exista uma credencial. |
--tools-only | Modo CI: cria uma credencial somente para ferramentas que o aplicativo desktop não carrega. |
--yes | Substitui a credencial de outra conta sem perguntar. |
setup-mcp
godot-cli setup-mcp <agent> [path] grava a configuração MCP do agente, fixada neste projeto por padrão. Os ids de agente e os arquivos de configuração estão listados em Conectando clientes de IA.
| Flag | Significado |
|---|---|
--list | Lista todos os ids de agente. |
--url <url> | Substituição do host do servidor, por exemplo, um servidor local. |
--token <token> | Substituição de token. Padrão GODOT_MCP_TOKEN. |
--no-pin | Grava a URL /mcp simples em vez da fixada. |
--oauth | Cloud: configuração apenas com URL; o agente faz login com o próprio OAuth. |
--regenerate-key | Cloud: cria uma nova chave de projeto e revoga a antiga. |
setup-skills
godot-cli setup-skills <agent> [path] grava arquivos SKILL.md para as famílias de ferramentas do addon na pasta de skills do agente (por exemplo, .claude/skills). Não precisa de um editor em execução. --list mostra o suporte a skills de cada agente.
configure
Lista ou altera quais ferramentas, prompts e recursos os clientes MCP veem, em .godot-mcp/features.json. Itens ocultos ainda são executados quando chamados pelo nome.
| Flag | Significado |
|---|---|
--list | Mostra a configuração atual. |
--enable-tools <names> / --disable-tools <names> | Mostra ou oculta ferramentas (separadas por vírgula). |
--enable-all-tools / --disable-all-tools | Mostra ou oculta todas as ferramentas. |
--enable-prompts <names> / --disable-prompts <names> | Mostra ou oculta prompts. |
--enable-all-prompts / --disable-all-prompts | Mostra ou oculta todos os prompts. |
--enable-resources <names> / --disable-resources <names> | Mostra ou oculta recursos. |
--enable-all-resources / --disable-all-resources | Mostrar ou ocultar todos os recursos. |
--agent <id> | Configura um agente por meio do binário do servidor gerenciado (requer install-plugin --with-server). |
--url <url> | Com --agent: substitui a URL do servidor. |
run-tool e run-system-tool
Chame uma ferramenta diretamente pela API HTTP do servidor: run-tool envia POST para /api/tools/<tool> e run-system-tool para /api/system-tools/<tool> (ferramentas ocultas de clientes MCP, como ping).
godot-cli run-tool rql-query ./MyGodotProject --input '{"query":"nodes | select name class"}'
godot-cli run-system-tool ping ./MyGodotProject| Opção | Significado |
|---|---|
--url <url> | URL base do servidor. |
--token <token> | Token Bearer. Padrão GODOT_MCP_TOKEN. |
--input <json> | Argumentos da ferramenta como uma string JSON. |
--input-file <file> | Lê os argumentos JSON de um arquivo. |
--raw | Imprime JSON bruto. |
--timeout <ms> | Tempo limite da requisição. Padrão 60000. |
Sem --url, o servidor é escolhido a partir de GODOT_MCP_HOST, depois de GODOT_MCP_CLOUD_URL, depois da nuvem quando GODOT_MCP_CONNECTION_MODE=Cloud, depois do servidor inscrito do projeto e, por fim, da porta local do projeto.
status e wait-for-ready
status detecta um editor em execução para o projeto e sonda o servidor (--url, --token, --timeout <ms>, padrão 5000). wait-for-ready consulta ping até o editor responder (--url, --token, --timeout <ms> padrão 120000, --interval <ms> padrão 3000). Use em scripts depois de open.
update
godot-cli update verifica no npm se há um godot-cli mais recente e o instala; --check apenas informa.
Relacionados
- O app AI Game Dev tem seu próprio CLI
gamedev: CLI do app. - Unity e Unreal têm
unity-mcp-clieunreal-mcp-cli: veja os wikis do Unity MCP e do Unreal MCP.