# godot-cli 레퍼런스 — Godot · AI Game Developer Wiki

install-plugin, login, setup-mcp부터 open, exec, run-tool, configure, install-extension까지 Godot MCP를 위한 모든 godot-cli 명령과 플래그를 정리합니다.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/godot/cli).

`godot-cli`는 npm에 게시된 Godot MCP용 명령줄 도구입니다. 애드온을 설치하고, 로그인하고, AI 에이전트 설정을 작성하며, 올바른 연결 설정으로 에디터를 빌드해 열고, 스크립트에서 도구를 호출합니다. 이 페이지는 `godot-cli` 0.34.0의 모든 명령과 해당 플래그를 나열합니다.

## 설치 및 기본 사항

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

Node.js `^20.19.0` 또는 `>=22.12.0`이 필요하며 Windows, macOS, Linux에서 동작합니다. 설치 없이도 모든 명령을 실행할 수 있습니다: `npx godot-cli <command>`.

대부분의 명령은 선택적 위치 인자 `[path]`(또는 `--path <path>`)로 프로젝트 폴더를 받으며 기본값은 현재 폴더입니다. 모든 명령은 진단 출력을 위한 `-v` / `--verbose`를 지원합니다.

## 명령 개요

| 명령 | 설명 |
| --- | --- |
| `install-plugin [path]` | 애드온을 설치하고, `.csproj`를 패치하고, 플러그인을 활성화합니다. |
| `install-extension <id> [path]` | `.csproj`에 확장 패키지를 추가하거나 업데이트합니다. |
| `remove-plugin [path]` | `project.godot`에서 애드온을 비활성화합니다(파일은 유지). |
| `create-project [path]` | 최소한의 Godot 4 프로젝트를 생성합니다. |
| `build [path]` | 프로젝트의 C# 어셈블리를 빌드합니다. |
| `open [path]` | 빌드한 뒤 연결 설정과 함께 Godot 에디터를 엽니다. |
| `close [path]` | 프로젝트에 대해 실행 중인 Godot 에디터를 종료합니다. |
| `exec [code]` | `script-execute`를 통해 에디터에서 C#을 실행합니다. |
| `login [path]` | 디바이스 플로우로 ai-game.dev에 로그인합니다. |
| `setup-mcp <agent> [path]` | AI 에이전트의 MCP 설정을 작성합니다. |
| `setup-skills <agent> [path]` | AI 에이전트용 스킬 파일을 생성합니다. |
| `configure [path]` | 도구, 프롬프트, 리소스를 표시하거나 숨깁니다. |
| `run-tool <tool> [path]` | HTTP를 통해 MCP 도구를 호출합니다. |
| `run-system-tool <tool> [path]` | HTTP를 통해 시스템 도구를 호출합니다. |
| `status [path]` | 에디터와 MCP 서버 상태를 확인합니다. |
| `wait-for-ready [path]` | 에디터가 `ping`에 응답할 때까지 기다립니다. |
| `update` | `godot-cli` 자체를 업데이트합니다. |

## install-plugin

`godot_mcp` 애드온을 처음부터 끝까지 설치합니다: GitHub에서 애드온 릴리스를 다운로드하거나(또는 로컬 사본을 복사), `.csproj`에 NuGet `PackageReference`와 확장 카탈로그 `<EmbeddedResource>`를 추가하고, `EnableDynamicLoading`을 설정하며, `project.godot`에서 플러그인을 활성화합니다. 다시 실행해도 안전합니다.

| 플래그 | 의미 |
| --- | --- |
| `--source <path>` | 다운로드하는 대신 로컬 폴더에서 애드온을 복사합니다(오프라인, 개발, CI). |
| `--version <x.y.z>` | 다운로드할 애드온 릴리스입니다. 기본값은 CLI의 버전입니다. `--source` 사용 시 무시됩니다. |
| `--with-server` | 릴리스 체크섬으로 검증한 뒤 일치하는 `gamedev-mcp-server` 바이너리도 함께 다운로드합니다. |
| `--server-source <path>` | 로컬 폴더 또는 `.zip`에서 서버를 설치합니다. `--with-server`를 포함합니다. |
| `--server-version <x.y.z>` | 다운로드할 서버 버전입니다. 기본값은 애드온에 고정된 서버 버전입니다. |
| `--enroll <code>` | 에이전트 등록 코드를 사용합니다(브라우저 없이 플러그인에 로그인). |
| `--enroll-stdin` | stdin에서 등록 코드를 읽어 셸 기록에 남지 않게 합니다. |
| `--base-url <url>` | 등록 코드를 사용할 클라우드 URL입니다. 기본값 `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]`는 확장 카탈로그에서 id(패키지 id 또는 이름)를 확인해 해당 `<PackageReference>`를 추가하거나 업데이트합니다. `--version <x.y.z>`는 최신 안정 버전 대신 정확한 버전을 요청합니다. 이후 `godot-cli build`를 실행하세요. [Extensions](https://ai-game.dev/ko/docs/wiki/godot/extensions)를 참고하세요.

## remove-plugin

`project.godot`의 `[editor_plugins]` 섹션에서 애드온을 비활성화합니다. `addons/godot_mcp/`나 `.csproj` 항목은 삭제하지 않습니다.

## create-project

최소한의 Godot 4 프로젝트(`project.godot`와 `icon.svg`)를 생성합니다. 기존 Godot, Unity 또는 Unreal 프로젝트를 덮어쓰지 않습니다.

| 플래그 | 의미 |
| --- | --- |
| `--dotnet` | `Godot.NET.Sdk` C# `.csproj`도 생성합니다(Godot MCP에 필요). |
| `--name <name>` | 프로젝트 이름입니다. 기본값은 폴더 이름입니다. |

## build

애드온이 다음 에디터 실행 시 로드되도록 프로젝트의 `.csproj`에 `dotnet build`를 실행합니다. `.csproj`가 없는 프로젝트는 건너뜁니다.

| 플래그 | 의미 |
| --- | --- |
| `--configuration <cfg>` | MSBuild 구성입니다. 기본값 `Debug`. |
| `--dotnet-path <path>` | `PATH`에 있는 것 대신 이 `dotnet` 실행 파일을 사용합니다. |

## open

C# 어셈블리를 빌드하고 Godot 에디터를 찾아 프로젝트를 엽니다. 빌드가 실패하면 에디터는 시작되지 않습니다. 에디터 탐색 순서는 `--editor-path`, `GODOT_BIN` 또는 `GODOT4_BIN` 환경 변수, `PATH`의 Godot 바이너리(Windows에서는 .NET 빌드 우선), 일반적인 설치 폴더 순입니다.

| 플래그 | 의미 |
| --- | --- |
| `--editor-path <path>` | 사용할 Godot 에디터 실행 파일입니다. |
| `--no-build` | C# 빌드를 건너뜁니다. |
| `--build-configuration <cfg>` | 사전 공개 빌드를 위한 구성입니다. 기본값은 `Debug`입니다. |
| `--no-connect` | `GODOT_MCP_*` 연결 변수 없이 엽니다. |
| `--mode <Cloud or Custom>` | `GODOT_MCP_CONNECTION_MODE`를 설정합니다. |
| `--url <url>` | `GODOT_MCP_HOST`를 설정합니다. |
| `--cloud-url <url>` | `GODOT_MCP_CLOUD_URL`을 설정합니다. |
| `--token <token>` | `GODOT_MCP_TOKEN`을 설정합니다. |
| `--auth <None or Required>` | `GODOT_MCP_AUTH_OPTION`을 설정합니다. |
| `--log-level <level>` | `GODOT_MCP_LOG_LEVEL`을 설정합니다(`Trace`, `Debug`, `Info`, `Warning`, `Error`, `None`). |
| `--headless` | 프로젝트의 로컬 서버에서 창 없는 에디터를 시작하고 준비될 때까지 기다립니다. 이미 실행 중인 에디터가 있으면 재사용합니다. |
| `--idle-timeout <seconds>` | `--headless`와 함께 사용: 도구 호출 없이 이 시간(초)이 지나면 종료합니다(`0` = 종료하지 않음). |
| `--ready-timeout <ms>` | `--headless`와 함께 사용: 에디터가 준비될 때까지 기다리는 시간입니다. |

## close

프로젝트에서 실행 중인 Godot 에디터를 정상적으로 종료합니다.

| 플래그 | 의미 |
| --- | --- |
| `--timeout <seconds>` | 정상 종료를 기다리는 시간입니다. 기본값 30. |
| `--force` | 시간 내에 종료되지 않으면 에디터를 강제 종료합니다. |
| `--owned-only` | `godot-cli`가 시작한 에디터(`exec`, `open --headless`)만 종료하고, 직접 실행한 에디터는 종료하지 않습니다. 종료 전에 열린 씬을 먼저 저장합니다. |
| `--token <token>` | `--owned-only`와 함께 사용: 베어러 토큰입니다. 기본값은 `GODOT_MCP_TOKEN`입니다. |

## exec

`script-execute` 도구로 프로젝트의 에디터에서 C#을 실행합니다. 코드는 일반 문장으로 구성되며, 마지막 식이 결과입니다. 프로젝트의 에디터가 실행 중이면 이를 재사용합니다(사용자의 에디터가 Custom 모드이고 로컬 서버가 시작되어 있어야 함). 그렇지 않으면 `exec`는 프로젝트를 빌드하고 로컬 서버에 연결된 헤드리스 에디터를 시작하며, 이 에디터는 호출 없이 `--idle`초가 지나면 종료됩니다(기본값 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
```

| 플래그 | 의미 |
| --- | --- |
| `--path <path>` | 프로젝트 폴더입니다. |
| `-f, --file <file>` | 파일에서 코드를 읽습니다(stdin의 경우 `-`). |
| `--using <namespace>` | 추가 네임스페이스입니다. 반복 지정 가능합니다. |
| `--include <path>` | `<project>/.ai-game-dev/snippets` 아래의 헬퍼 `.cs` 파일 또는 폴더입니다. 반복 지정 가능합니다. |
| `--window` | 헤드리스 대신 창을 띄워 에디터를 시작합니다. |
| `--idle <seconds>` | 시작된 에디터가 종료되기까지의 유휴 시간입니다(`0` = 종료하지 않음). |
| `--ready-timeout <ms>` | 시작된 에디터를 기다리는 시간입니다. |
| `--timeout <ms>` | 도구 호출 타임아웃입니다. 기본값 310000. |
| `--no-build` | 에디터를 시작하기 전에 빌드하지 않습니다. |
| `--editor-path <path>` | Godot 에디터 실행 파일입니다. |
| `--url <url>` | 로컬 MCP 서버 URL입니다. 기본값: 프로젝트의 로컬 포트. |
| `--token <token>` | 베어러 토큰입니다. 기본값 `GODOT_MCP_TOKEN`. |
| `--raw` | 원시 도구 응답 JSON을 출력합니다. |

컴파일 오류는 스니펫의 해당 줄을 가리키며 코드 1로 종료됩니다.

## login

OAuth 2.1 디바이스 플로로 ai-game.dev에 로그인하고 자격 증명을 `~/.ai-game-dev/credentials.json`에 저장하면 에디터가 이를 인식합니다. [Connecting AI clients](https://ai-game.dev/ko/docs/wiki/godot/connecting-ai-clients#device-flow)를 참고하세요.

| 플래그 | 의미 |
| --- | --- |
| `--project <path>` | 대신 `<path>/.ai-game-dev/` 아래에 프로젝트별 자격 증명을 저장합니다. |
| `--base-url <url>` | 다른 서버에 로그인합니다. 기본값 `https://ai-game.dev`. |
| `--force` | 자격 증명이 이미 있어도 다시 로그인합니다. |
| `--tools-only` | CI 모드: 데스크톱 앱이 인식하지 않는 도구 전용 자격 증명을 생성합니다. |
| `--yes` | 다른 계정의 자격 증명을 묻지 않고 대체합니다. |

## setup-mcp

`godot-cli setup-mcp <agent> [path]`는 에이전트의 MCP 구성을 작성하며, 기본적으로 이 프로젝트에 고정됩니다. 에이전트 id와 구성 파일은 [Connecting AI clients](https://ai-game.dev/ko/docs/wiki/godot/connecting-ai-clients#agents)에 나열되어 있습니다.

| 플래그 | 의미 |
| --- | --- |
| `--list` | 모든 에이전트 id를 나열합니다. |
| `--url <url>` | 서버 호스트 재정의입니다. 예를 들어 로컬 서버를 지정할 수 있습니다. |
| `--token <token>` | 토큰 재정의입니다. 기본값 `GODOT_MCP_TOKEN`. |
| `--no-pin` | 고정된 URL 대신 일반 `/mcp` URL을 작성합니다. |
| `--oauth` | 클라우드: URL만 구성하며, 에이전트가 자체 OAuth로 로그인합니다. |
| `--regenerate-key` | 클라우드: 새 프로젝트 키를 만들고 이전 키를 폐기합니다. |

## setup-skills

`godot-cli setup-skills <agent> [path]`는 애드온의 도구 패밀리에 대한 `SKILL.md` 파일을 에이전트의 스킬 폴더(예: `.claude/skills`)에 작성합니다. 실행 중인 에디터는 필요하지 않습니다. `--list`는 각 에이전트의 스킬 지원 여부를 보여줍니다.

## configure

MCP 클라이언트가 보는 도구, 프롬프트, 리소스를 `.godot-mcp/features.json`에서 나열하거나 변경합니다. 숨겨진 항목도 이름으로 호출하면 여전히 실행됩니다.

| 플래그 | 의미 |
| --- | --- |
| `--list` | 현재 구성을 표시합니다. |
| `--enable-tools <names>` / `--disable-tools <names>` | 도구를 표시하거나 숨깁니다(쉼표로 구분). |
| `--enable-all-tools` / `--disable-all-tools` | 모든 도구를 표시하거나 숨깁니다. |
| `--enable-prompts <names>` / `--disable-prompts <names>` | 프롬프트를 표시하거나 숨깁니다. |
| `--enable-all-prompts` / `--disable-all-prompts` | 모든 프롬프트를 표시하거나 숨깁니다. |
| `--enable-resources <names>` / `--disable-resources <names>` | 리소스를 표시하거나 숨깁니다. |
| `--enable-all-resources` / `--disable-all-resources` | 모든 리소스를 표시하거나 숨깁니다. |
| `--agent <id>` | 관리되는 서버 바이너리를 통해 에이전트를 구성합니다(`install-plugin --with-server` 필요). |
| `--url <url>` | `--agent` 사용 시: 서버 URL을 재정의합니다. |

## run-tool과 run-system-tool

서버의 HTTP API를 통해 도구를 직접 호출합니다. `run-tool`은 `/api/tools/<tool>`로, `run-system-tool`은 `/api/system-tools/<tool>`로 POST합니다(MCP 클라이언트에서 숨겨진 도구, 예: `ping`).

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

| 플래그 | 의미 |
| --- | --- |
| `--url <url>` | 서버 기본 URL. |
| `--token <token>` | Bearer 토큰. 기본값 `GODOT_MCP_TOKEN`. |
| `--input <json>` | JSON 문자열로 된 도구 인자. |
| `--input-file <file>` | 파일에서 JSON 인자를 읽습니다. |
| `--raw` | 원시 JSON을 출력합니다. |
| `--timeout <ms>` | 요청 타임아웃. 기본값 60000. |

`--url`이 없으면 서버는 `GODOT_MCP_HOST`, 그다음 `GODOT_MCP_CLOUD_URL`, 그다음 `GODOT_MCP_CONNECTION_MODE=Cloud`일 때 클라우드, 그다음 프로젝트에 등록된 서버, 마지막으로 프로젝트의 로컬 포트 순으로 선택됩니다.

## status와 wait-for-ready

`status`는 프로젝트에서 실행 중인 에디터를 감지하고 서버를 프로브합니다(`--url`, `--token`, `--timeout <ms>`, 기본값 5000). `wait-for-ready`는 에디터가 응답할 때까지 `ping`을 폴링합니다(`--url`, `--token`, `--timeout <ms>` 기본값 120000, `--interval <ms>` 기본값 3000). `open` 뒤에 스크립트에서 사용하세요.

## update

`godot-cli update`는 npm에서 더 새로운 `godot-cli`를 확인해 설치하며, `--check`는 보고만 합니다.

## 관련 항목

- AI Game Dev 앱에는 자체 `gamedev` CLI가 있습니다: [App CLI](https://ai-game.dev/ko/docs/wiki/app/cli).
- Unity와 Unreal에는 `unity-mcp-cli`와 `unreal-mcp-cli`가 있습니다: [Unity MCP](https://ai-game.dev/ko/docs/wiki/unity)와 [Unreal MCP](https://ai-game.dev/ko/docs/wiki/unreal) 위키를 참고하세요.

---

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

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