godot-cli

Read, edit, and author Godot scene and resource files from the command line, without launching the editor.

Documentation: unabated-games.github.io/godot-cli

godot-cli parses .tscn, .tres, and project.godot into a document model, understands Godot's identifier systems and Variant text, and writes files back the way the editor writes them. Output is verified byte-for-byte against saves the Godot editor itself produced.

Every command works from argv or from a JSON request, and returns the same JSON envelope — so it reads the same to a person at a terminal, a CI script, or an LLM agent.

$ godot-cli scene new --output level.tscn --root-name Level --root-type Node2D
$ godot-cli scene node add level.tscn --parent /root/Level --name Player --type CharacterBody2D
$ godot-cli scene instance add level.tscn --parent /root/Level --scene res://ui/hud.tscn --name HUD
$ godot-cli scene validate level.tscn --project-root . --json
{"ok":true,"version":"0.20.0","command":["scene","validate"],"data":{"path":"level.tscn","issues":[]},...}

That scene is a normal Godot scene: the hierarchy lives in the file, the way a human would have built it in the editor. No _ready() spawning, no hand-edited scene text.

Validation reads the file the way the engine would — a property whose value is the wrong type for its class, or a connection to a signal the class does not emit, is an error rather than something that only shows up when you press Play. And a change can be checked by running it:

$ godot-cli scene describe level.tscn --project-root . --json     # the whole scene in one call
$ godot-cli project run --project-root . --frames 30 \
    --click /root/Level/HUD/Play@20 --frame-at 0 --json           # run it, click a button, keep a before-and-after pair

The run returns the frame it drew and every error line from the log, so "done" means a screen someone looked at rather than a command that exited 0.

Install

curl -fsSL https://raw.githubusercontent.com/unabated-games/godot-cli/main/install.sh | bash
source "$HOME/.godot-cli/env.sh"
godot-cli --version

Installs the binary, scene templates, agent docs and examples, shell completions, and the man page into ~/.godot-cli. No toolchain needed — it downloads the release archive for your platform and verifies it against the release checksums.

From a checkout instead:

zig build                 # binary at zig-out/bin/godot-cli
./install.sh              # build, then install to ~/.godot-cli

Releases ship Linux (musl), macOS, and Windows binaries for x86_64 and aarch64. On Windows the same install.sh works from Git Bash, MSYS2 or Cygwin. See Getting started for the full install matrix, agent setup, and a first-scene walkthrough.

What it does

Layer	Commands
Godot ID primitives	uid encode/decode, uid create-for-path, uid read (a file's recorded UID, binary resources included), scene-local ids, .godot/uid_cache.bin reads, id sessions
Read	scene inspect, resource inspect, scene node list/get, parsed Variant values with types
Validate	scene validate, validate-batch, compare-godot, round-trip
Edit and author	scene new, node add/remove/rename/reparent/move, ext add, sub add, instance add, set-property, normalize, retarget-ext
Declarative editing	scene plan, scene apply --intent/--patch, scene diff, scene restore, batch
Project settings	project show/apply, input, settings, autoload, plugins, rendering, physics
Export presets	project export list/show/options/apply/validate/build, with secrets kept in .godot/export_credentials.cfg
Component catalog	catalog add, scan, list, show, validate, search, export, relink

Full detail, option by option: Command reference — or man godot-cli after install.

For LLM agents

The scene-authoring surface exists because agents are bad at editing .tscn text and reach for runtime load().instantiate() instead. godot-cli gives them tree operations, structured errors, and a component catalog describing which scene to instance and when.

./install.sh --install-skill   # skill for Cursor, Claude Code, OpenCode, ~/.agents
claude mcp add godot-cli -- godot-cli mcp --project-root .   # or serve it over MCP

godot-cli mcp serves every command as an MCP tool over stdio, with schemas generated from the command tree, the agent docs as resources, and the project catalog as a live resource. See getting started for the Claude Code, Cursor, and OpenCode config.

• Agent quickstart — one page, the whole workflow
• Agent scene authoring — recipes, patch and intent format, anti-patterns
• Agent batch commands — multi-step workflows in one invocation
• godot-cli mcp --project-root . — the MCP server; docs/mcp_tools.json carries a worked request per command
• godot-cli reference --format json — the whole command surface as data

Documentation

The full documentation site is at unabated-games.github.io/godot-cli, including how-to guides for scene authoring, the component catalog, batch edits, and agent setup.

Doc	What it covers
Getting started	Install, first scene, agent setup
Command reference	Every command, option, and exit code (generated)
About godot-cli	What it is, why it exists, what it is not
Development principles	CLI and JSON contracts every command follows
Documentation index	Everything else, including design docs and roadmaps

Status

Early development, released under semantic versioning. The file format work — ID generation, UID cache, Variant parsing, save round-trip — is verified in unit tests and in a suite that compares godot-cli's output byte-for-byte against files the editor saved. CI runs that suite against Godot 4.7 and 4.7.2, and against the newest 4.8 prerelease as a non-blocking check so a format change shows up here before it shows up in your diff.

Scene authoring, the component catalog, project.godot editing, and batch workflows are all implemented; see the scene authoring roadmap for how they fit together.

Building

Requires Zig 0.17.0 or later. A Godot install is needed only to run the game or the round-trip suite; the files godot-cli writes target Godot 4.6 and later, since every node line carries the unique_id the engine added in 4.6.

zig build                # binary at zig-out/bin/godot-cli
zig build test           # unit tests + CLI smoke tests
zig build test-godot     # round-trip against a real Godot save (-Dgodot=/path)
zig build docs           # regenerate command reference, man page, completions

CONTRIBUTING.md covers the development setup, what CI checks, and the conventions new commands follow. Participation is covered by our Code of Conduct; to report a security issue, see SECURITY.md. Releases follow RELEASING.md.

License

MIT, copyright © 2026 Unabated Games — see LICENSE.

Contains code ported from the Godot Engine (MIT) and from PCG (Apache-2.0). Those notices, and what was changed, are recorded in THIRDPARTY.md; the Apache-2.0 text is at third_party/licenses/.

"Godot" and the Godot Engine logo are trademarks of the Godot Foundation. This project is not affiliated with, endorsed by, or sponsored by the Godot Foundation or the Godot Engine project.