# Referência do godot-cli — Godot · AI Game Developer Wiki

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.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/godot/cli).

`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

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

Requer 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`. |

```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]` 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](https://ai-game.dev/pt-br/docs/wiki/godot/extensions).

## 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).

```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 | 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](https://ai-game.dev/pt-br/docs/wiki/godot/connecting-ai-clients#device-flow).

| 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](https://ai-game.dev/pt-br/docs/wiki/godot/connecting-ai-clients#agents).

| 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`).

```bash
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](https://ai-game.dev/pt-br/docs/wiki/app/cli).
- Unity e Unreal têm `unity-mcp-cli` e `unreal-mcp-cli`: veja os wikis do [Unity MCP](https://ai-game.dev/pt-br/docs/wiki/unity) e do [Unreal MCP](https://ai-game.dev/pt-br/docs/wiki/unreal).

---

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

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