godot-repl

Godot REPL

Send any GDScript to a running Godot editor (or its runtime child process). The engine evaluates it on the main thread; you get a structured result, captured print() output, or a typed error.

It's a REPL. Anything the engine can execute, you can send. Top-level declarations (var, func, class, const, signal, enum) persist across calls in the same session. The last expression auto-returns when it's not a statement.

Setup check

The editor must be running with the godot-repl addon enabled. Verify:

test -f "<project>/.godot/repl_endpoint.json" && cat "<project>/.godot/repl_endpoint.json"

{"editor":  {"host": "127.0.0.1", "port": 6010, "pid": 12345},
 "runtime": {"host": "127.0.0.1", "port": 6011, "pid": 12346}}

If that file is missing, the editor isn't running or the addon isn't enabled — use the godot-bootstrap skill.

Quick start — the wrapper

Two wrappers, same flags, same behavior — pick the one for your platform:

Platform	Wrapper
Windows (cmd, PowerShell, or Git-Bash)	addons\godot-repl\repl.bat
Linux, macOS	addons/godot-repl/repl.sh

Both wrappers handle endpoint discovery, JSONRPC envelope construction, NDJSON stream reading, and result parsing. Pass GDScript, get the result.

Inline (one-liner)

:: Windows
addons\godot-repl\repl.bat -e "Engine.get_version_info().string"
:: → 4.6.stable

# Linux / macOS
./addons/godot-repl/repl.sh -e 'Engine.get_version_info().string'
# → 4.6.stable

Multi-line GDScript (avoid quote-escaping)

GDScript doesn't support ; as a statement separator, so anything beyond one expression needs newlines. Use stdin or a file.

PowerShell here-string:

@'
var root = EditorInterface.get_edited_scene_root()
return root.get_child_count()
'@ | & "addons\godot-repl\repl.bat" -

cmd doesn't have heredocs — use -f with a file:

:: write query.gd via your editor / Write tool, then:
addons\godot-repl\repl.bat -f query.gd

bash heredoc:

./addons/godot-repl/repl.sh - <<'EOF'
var root = EditorInterface.get_edited_scene_root()
return root.get_child_count()
EOF

Full flag table and behavior in references/wrapper.md.

Don't guess — introspect

Godot's ClassDB exposes every class, method, property, and signal at runtime. Before calling something you're not 100% sure about, verify it exists — it's a one-liner via REPL and the answer is exact to your Godot version:

./repl.sh -e 'ClassDB.class_has_method("Node", "add_child")'
# → true

# Find method by partial name
./repl.sh - <<'EOF'
return ClassDB.class_get_method_list("Camera2D").filter(
    func(m): return "zoom" in m.name
).map(func(m): return m.name)
EOF

Common entry points (one-liners worth memorizing):

Want to know	Call
Does this method exist?	ClassDB.class_has_method("Node", "add_child")
What's the full method signature?	ClassDB.class_get_method_list("Node") (filter by .name)
What properties does this class have?	ClassDB.class_get_property_list("Node")
What signals?	ClassDB.class_get_signal_list("Node")
Is X a subclass of Y?	ClassDB.is_parent_class("Camera2D", "Node2D")
What singletons are loaded?	Engine.get_singleton_list()
What's my Godot version?	Engine.get_version_info()

More patterns (find by intent, list inheritors, dump enum constants, etc.) in references/recipes.md → "Discovery & introspection."

When ClassDB isn't enough (conceptual questions, usage idioms, lifecycle ordering), check Godot's official docs at https://docs.godotengine.org/en/<version>/ — get <version> from repl.info. ClassDB tells you what exists; the docs tell you what's idiomatic.

Endpoints

• editor — modify .tscn, change ProjectSettings, use EditorInterface, save resources, trigger Play
• runtime (only when the project is running) — inspect a live SceneTree, mutate Node properties on a playing game, read runtime state

Default is editor. Pass --target runtime to the wrapper for the runtime endpoint.

Ports are dynamic. The addon picks the lowest free port from 6010..6020 for editor and 6011..6021 for runtime. The wrappers read <project>/.godot/repl_endpoint.json automatically; raw-TCP clients must do the same — never hardcode 6010.

Methods

Method	Purpose
repl.eval	Evaluate GDScript, return result
repl.validate	Compile-only check, no execution, no side effects
repl.reset	Clear a session's accumulated declarations
repl.cancel	Stop the server from waiting on an in-flight eval
repl.list_sessions	Enumerate active sessions
repl.info	Server metadata (version, target, uptime, capabilities)
repl.abilities / repl.get_ability	Discover godot-agent-* extension packages

Full JSONRPC schema, response shapes, and notification details: references/methods.md.

Async work

await works as normal — the server awaits the resulting Signal and responds with the final value:

await get_tree().create_timer(2.0).timeout
var img = await ResourceLoader.load_threaded_get_resource("res://big.png")
return img.get_size()

Default timeout is 60s. Override with --timeout-ms (wrapper) or params.timeout_ms (raw JSONRPC).

Error kinds

The result.kind tells you what happened:

• value — eval succeeded; result.value is the return value
• compile_error — GDScript didn't compile
• runtime_error — code ran but the engine reported an error
• timeout — timeout_ms exceeded
• cancelled — another agent called repl.cancel

RPC-layer errors (error.code set, not result.kind) — PARSE_ERROR, METHOD_NOT_FOUND, INVALID_PARAMS — indicate protocol failures, not user code failures.

Going further

• references/methods.md — full JSONRPC schema for every method and notification
• references/wrapper.md — repl.sh / repl.bat flags and behavior
• references/raw-client.md — raw NDJSON-over-TCP clients (PowerShell / bash / Python) for mid-flight cancel, batch, persistent connections, or wrapper bypass
• references/recipes.md — common GDScript snippets plus the Godot-side quirks you'll meet (PackedScene.pack child-drop, ProjectSettings.save race, ConfigFile cache, async open_scene_from_path, lambda body limits, multi-line dict indentation)
• references/abilities.md — author a godot-agent-* package that registers with this REPL