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.

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.

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

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

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.

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.

Requires Zig 0.16.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.

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.