godot-cli

简体中文

godot-cli is a structured command-line interface that gives coding agents Godot-specific automation capabilities. It exposes typed, discoverable commands for project operations, headless scene/resource/script work, process lifecycle, and runtime inspection and testing while leaving ordinary file editing to the agent's native tools.

Features

• Layered command discovery — use --help for readable guidance, commands for the catalog, and --help-json for an exact schema.
• Typed input validation — command flags are generated from TypeBox schemas and validated before adapter execution.
• Readable by default, structured on demand — interactive output is concise text; --json returns stable success or error envelopes for automation.
• Project operations — inspect or create a project and manage Godot project settings.
• Headless Godot operations — create/read scenes, add/remove nodes, create/inspect resources, and validate scripts through Godot.
• Runtime control — start and stop a Godot scene, inspect process/runtime state and trees, read logs, send input, wait for frames, and assert state.
• Write previews — supported write-risk commands can return planned changes through global --dry-run before mutation.
• Agent Skill — one routing skill progressively loads only the workflow reference needed for the current task.

Requirements and compatibility

• Node.js 20.9 or newer.
• Godot available as godot/godot4, supplied with --godot, or configured through GODOT_BIN.
• The release smoke workflow is tested with Godot 4.7.1.

Godot behavior can vary by engine version and project configuration. “Tested with” is not a promise of compatibility with every Godot 4 release.

Installation

Install the CLI package globally:

npm install --global @4fu/godot-cli
godot-cli --help

Select a non-default Godot binary either per invocation or through the environment:

godot-cli --godot /path/to/godot --project . project inspect
GODOT_BIN=/path/to/godot godot-cli --project . project inspect

Quick start

Inspect a project and scene:

godot-cli --project . project inspect
godot-cli --project . scene read --path res://main.tscn --depth 4 --limit 200

Preview, apply, and verify a scene change:

godot-cli --project . --dry-run scene add-node \
  --path res://main.tscn --parent . --type Node2D --name SpawnPoint

godot-cli --project . scene add-node \
  --path res://main.tscn --parent . --type Node2D --name SpawnPoint

godot-cli --project . scene read --path res://main.tscn

Start a scene, inspect it, and always stop the process:

godot-cli --project . --timeout 15000 process run --scene res://main.tscn
godot-cli --project . runtime state
godot-cli --project . runtime tree --depth 3
godot-cli --project . process stop

Live editor mode

Start and stop the project editor session with godot-cli editor start and godot-cli editor stop (--headless true is intended for automation). Commands under editor operate on the editor's current scene, selection, filesystem and debugger state, including unsaved changes. Scene mutations are registered in Godot's native editor undo history; undo/redo remains driven by the editor UI because Godot does not expose a manager-safe scripted command for it. --expected-scene res://... can guard operations against a changed scene tab.

Command discovery

Start with the built-in human-readable help. Help is available at the root, command-family, and command levels:

godot-cli --help
godot-cli scene --help
godot-cli scene add-node --help

List all commands, or only one family:

godot-cli commands
godot-cli commands scene

Human-readable discovery uses copyable shell names such as scene add-node. Add --json when a script needs the stable catalog, whose canonical paths use domain/command:

godot-cli commands --json

Use --help-json only when an automation client needs the exact mode, wire route, risk, input/output schemas, CLI bindings, and timeout metadata:

godot-cli scene add-node --help-json
godot-cli runtime assert --help-json

Command families

Family	Commands
System	Godot version plus ClassDB class search and API metadata
Project	inspection/creation, settings, autoloads, input actions, layers, plugins, translations, main scene, export presets, and export
Scene	read/create/validate, node add/remove/properties/structure, packed-scene instantiation, script attachment, and persistent signals
Script	validate one/batch/all, diagnostics, symbols, C# scaffolding, and guarded project-script execution
Resource	create/inspect/set/duplicate/resave/UID and shader management
Process	process/run, process/stop, process/logs, process/state
Editor	live scenes/selection/nodes/properties with native undo history, scene tabs/save, filesystem scan/reimport, and debugger state
Runtime	state/tree/node mutation/property/method/groups/signals, visible UI, engine/window/performance, scene switching, pause/step, viewport, multi-device input, waits/assertions, screenshots, and cursor logs

Use discovery rather than this summary for authoritative flags and schemas.

Execution model

Commands are dispatched to one of four execution modes:

Mode	Responsibility
Local	Godot version lookup, project/process lifecycle, export, and guarded script execution
Headless	Isolated Godot process for scene, resource, script, and project inspection/mutation
Runtime	Authenticated loopback connection to the scene started by process run
Editor	Authenticated loopback connection to the live editor started by editor start

The command catalog owns the public names and schemas; adapters translate validated inputs into backend operations. This keeps shell syntax independent from backend wire routes.

Global options

Option	Description
--project <path>	Select the project root; defaults to the current directory
--godot <path>	Select the Godot executable
--timeout <ms>	Set a bounded operation timeout
--dry-run	Preview supported write-risk operations
--allow <capability>	Grant a guarded capability, repeatable
--session <path>	Override the runtime session file
--json	Emit stable machine-readable JSON
--pretty	Emit indented JSON; implies --json

Global options may appear before or after the command words.

Output and exit behavior

Interactive commands are human-readable by default. Field names remain unchanged so exact values are easy to identify:

Success
name: Example project
path: /projects/example

Failures identify the stable error code without wrapping the entire response in JSON:

Error [INVALID_INPUT]: Unknown option "--paht". Did you mean --path?

Add --json when output will be parsed, transported, or stored as a stable automation result. Successful JSON execution:

{"ok":true,"data":{}}

Failed execution:

{"ok":false,"error":{"code":"ERROR_CODE","message":"Description","details":{}}}

details is optional. --pretty implies --json and only changes indentation. rpc --stdin and --help-json always emit JSON because they are machine interfaces. Invalid command input exits with status 2; backend or assertion failures exit with status 1.

Paths, writes, and guarded operations

• Use the coding agent's native file tools to read, search, create, patch, rename, or delete ordinary project files and script source.
• Write destinations and scripts use project-local res:// paths. Commands that read or instantiate an existing scene/resource also accept uid:// references and resolve them through Godot's UID cache.
• Ordinary lexical traversal outside the selected project is rejected. This is a project-boundary check, not an OS-level sandbox.
• Preview write-risk commands with --dry-run, review planned_changes (or data.planned_changes with --json), and then repeat the command without --dry-run.
• --dry-run is for supported writes; it does not make process or runtime execution commands inert.
• Guarded operations require an explicit matching --allow value. Inspect the returned policy error and command schema rather than guessing.
• Keep source control or backups for important projects; a preview is not a backup.

Runtime lifecycle and limits

process run starts Godot headlessly by default and stores an authenticated loopback session under the selected project (or at --session). Runtime commands must use the same project/session selection. Always call process stop in cleanup, including after a failed test.

The current public command surface has these deliberate boundaries:

• scene read defaults to at most 4 levels and 200 nodes and reports truncated/node_count. Use --node, --depth, and --limit to narrow or expand a read; use --include-properties false for a hierarchy-only overview.
• The default headless runtime can report viewport size and visible Control bounds/focus, but uses Godot's dummy renderer and cannot capture pixels. Where a display and rendering driver are available, start with process run --headless false before using runtime screenshot; otherwise it returns SCREENSHOT_UNAVAILABLE.
• runtime call and script run require --allow call_method and --allow script_run respectively. Script execution accepts only project-local res:// scripts that extend SceneTree; arbitrary source evaluation is not provided.
• Live editor selection, Inspector state, native editor Undo/Redo, import queues, and unsaved in-memory scenes are not represented by headless or runtime sessions.
• Paths are bounded at the application level but the CLI is not a substitute for OS process isolation when operating on untrusted projects.

Agent Skill

The repository ships one discoverable routing skill at .agents/skills/using-godot-cli. Its SKILL.md contains shared rules and routes agents to one of five references only when needed: command discovery, scenes/resources, scripts/files, runtime testing, or editor workflows.

List or install it with the open Agent Skills CLI:

npx skills add 4fuu/godot-cli --list
npx skills add 4fuu/godot-cli --skill using-godot-cli -y

From a local checkout:

npx skills add . --list
npx skills add . --skill using-godot-cli -y

Development and verification

Build from a source checkout:

npm install
npm run build
node dist/cli.js commands

Formatting

Install uv for the pinned GDScript formatter, then run:

npm run format
npm run format:check

Prettier formats TypeScript, tests, and JSON. gdformat 4.5.0 formats and validates the GDScript under godot/.

Verification

npm test
npm run build
npm pack --dry-run

Run tests against an explicit Godot binary:

GODOT_BIN=/path/to/godot npm test

Before publishing, verify at minimum: command catalog/schema tests, project containment, dry-run non-mutation, skill discovery, package contents, scene dry-run/read, and the process run → runtime state/tree → process stop lifecycle.

License

MIT