Command reference

This page is generated from the CommandSpec tree inside godot-cli by zig build docs, and CI fails if it drifts from the binary. The same content is available offline as man godot-cli, and as data through godot-cli reference --format json.

godot-cli — Create, edit, and manipulate Godot scenes and resource files

Every command accepts the global options, and with --json returns the envelope described in development principles.

godot-cli [global options] <command> [command options] [args...]

Global options

Option	Value	Description
`-h`, `--help`	—	Show help and exit
`--version`	—	Show version and exit
`--json`	—	Emit machine-readable JSON output
`-v`, `--verbose`	—	Enable verbose logging on stderr
`--request`	`<value>`	Run using a JSON command descriptor
`--request-file`	`<path>`	Read JSON command descriptor from a file
`--request-stdin`	—	Read JSON command descriptor from stdin

Command index

Command	Summary
`godot-cli help`	Show help for a command
`godot-cli ping`	Framework health check
`godot-cli uid`	Godot-compatible resource and scene ID helpers
`godot-cli uid encode`	Encode a numeric Resource UID to uid:// text
`godot-cli uid decode`	Decode uid:// text to a numeric Resource UID
`godot-cli uid create-for-path`	The UID Godot would assign a new file (to read a file's existing UID, use uid read)
`godot-cli uid read`	Read the UID a file records, from the file itself
`godot-cli uid scene-id`	Scene-local 5-character unique id helpers
`godot-cli uid scene-id generate`	Generate scene unique ids with a deterministic seed
`godot-cli uid cache`	Inspect project uid_cache.bin
`godot-cli uid cache list`	List all UID cache entries
`godot-cli uid cache lookup`	Resolve uid:// text to path or path to uid:// text
`godot-cli uid session`	Persistent ext_resource id session cache
`godot-cli uid session import`	Import ext_resource ids from a Godot-saved scene
`godot-cli scene`	Inspect and edit Godot scene files
`godot-cli scene new`	Create a new empty scene file
`godot-cli scene describe`	Everything about a scene in one call: nodes with properties, connections, references, scripts
`godot-cli scene refs`	List ext_resource references in a scene
`godot-cli scene ext`	Add or remove external resources
`godot-cli scene ext add`	Add an ext_resource section
`godot-cli scene ext remove`	Remove an ext_resource by id
`godot-cli scene sub`	Add or remove sub-resources
`godot-cli scene sub add`	Add a sub_resource section
`godot-cli scene sub remove`	Remove a sub_resource by id
`godot-cli scene inspect`	Parse a .tscn file and report structure and ID issues
`godot-cli scene node`	List and query scene node tree
`godot-cli scene node list`	List all nodes in a scene with paths and section lines
`godot-cli scene node get`	Get one node by viewport path or by name
`godot-cli scene node add`	Add a child node under a parent path
`godot-cli scene node remove`	Remove a node by viewport path
`godot-cli scene node rename`	Rename a node and rewrite descendant parent attributes
`godot-cli scene node reparent`	Move a node under a new parent path
`godot-cli scene connection`	Signal connections stored in the scene ([connection] sections)
`godot-cli scene connection list`	List signal connections with from/to as viewport paths
`godot-cli scene connection add`	Connect a signal from one node to a method on another
`godot-cli scene connection remove`	Remove a signal connection
`godot-cli scene extract`	Move a subtree into its own scene and instance it back in place
`godot-cli scene instance`	Add instanced PackedScene nodes
`godot-cli scene instance add`	Instance a PackedScene under a parent node
`godot-cli scene template`	Built-in scene templates for scaffolding
`godot-cli scene template list`	List built-in scene templates
`godot-cli scene template show`	Show template metadata, node tree, and sections
`godot-cli scene template copy`	Copy a template to a new scene file
`godot-cli scene recipes`	List the intent recipes and the fields each takes
`godot-cli scene plan`	Expand intent JSON to a patch and preview (no write)
`godot-cli scene apply`	Apply a declarative JSON patch to a scene
`godot-cli scene diff`	Compare node trees between two scenes
`godot-cli scene restore`	Restore a scene from a snapshot file
`godot-cli scene validate`	Validate scene IDs and references (fails on errors)
`godot-cli scene validate-batch`	Validate multiple scene files (aggregated JSON, exit 1 on any error)
`godot-cli scene set-property`	Set a property on a node section and save the scene
`godot-cli scene normalize`	Repair scene-local IDs and sort ext_resource sections for save
`godot-cli scene retarget-ext`	Replace ext_resource paths across one or more files
`godot-cli scene round-trip`	Parse and rewrite a scene; fail if structure is not preserved
`godot-cli scene compare-godot`	Compare a scene to a Godot headless save (semantic match)
`godot-cli resource`	Inspect and edit Godot resource files
`godot-cli resource new`	Create a new .tres resource file
`godot-cli resource sub`	Sub-resources embedded in a .tres
`godot-cli resource sub add`	Add a sub_resource; reference it as SubResource("<id>")
`godot-cli resource sub remove`	Remove a sub_resource by id
`godot-cli resource ext`	External resource references in a .tres
`godot-cli resource ext add`	Register an external file; reference it as ExtResource("<id>")
`godot-cli resource ext remove`	Remove an ext_resource by id
`godot-cli resource inspect`	Parse a .tres file and report structure and ID issues
`godot-cli resource validate`	Validate resource IDs and references (fails on errors)
`godot-cli resource validate-batch`	Validate multiple resource files (aggregated JSON, exit 1 on any error)
`godot-cli resource set-property`	Set a property on a resource section and save
`godot-cli resource normalize`	Repair scene-local IDs and sort ext_resource sections for save
`godot-cli resource retarget-ext`	Replace ext_resource paths across one or more files
`godot-cli resource round-trip`	Parse and rewrite a resource file; fail if structure is not preserved
`godot-cli resource compare-godot`	Compare a resource to a Godot headless save (semantic match)
`godot-cli catalog`	Project component catalog
`godot-cli catalog add`	Create or update a JSON catalog manifest for a scene
`godot-cli catalog relink`	Repoint manifests whose scene has moved
`godot-cli catalog scan`	Scan project for catalog manifests
`godot-cli catalog list`	List valid catalog entries
`godot-cli catalog show`	Show merged catalog entry by id
`godot-cli catalog validate`	Validate catalog manifests in a project
`godot-cli catalog search`	Search project catalog entries and builtins
`godot-cli catalog export`	Export agent digest markdown
`godot-cli batch`	Run multiple CLI commands in one invocation
`godot-cli project`	Read and write Godot project.godot settings
`godot-cli project new`	Create a project.godot in a new or empty folder
`godot-cli project import`	Run Godot's headless import so new files get UIDs and .import data
`godot-cli project resave`	Have Godot load a scene or resource and save a copy, the reference for compare-godot
`godot-cli project run`	Run the game for a few frames and capture the last frame and the log
`godot-cli project show`	Summarize key project.godot configuration
`godot-cli project move`	Move or rename a file and repoint every reference to it
`godot-cli project apply`	Apply unified project intent JSON (input, settings, autoload, plugins, rendering, physics)
`godot-cli project input`	Input Map actions in project.godot
`godot-cli project input list`	List input actions
`godot-cli project input apply`	Apply input map intent JSON (merge/replace per action)
`godot-cli project input validate`	Validate [input] section event objects
`godot-cli project settings`	Scalar project settings (application, display, layer_names, …)
`godot-cli project settings list`	List settings (optional --section filter)
`godot-cli project settings get`	Get one setting value
`godot-cli project settings set`	Set one setting value
`godot-cli project settings apply`	Apply settings intent JSON (per-key merge)
`godot-cli project settings validate`	Validate res:// paths in settings
`godot-cli project autoload`	Autoload singletons in project.godot
`godot-cli project autoload list`	List autoload entries
`godot-cli project autoload apply`	Apply autoload intent JSON (merge by name; optional replace_all)
`godot-cli project autoload validate`	Validate autoload paths and names
`godot-cli project plugins`	Editor plugins enable/disable in project.godot
`godot-cli project plugins list`	List addons and enabled state
`godot-cli project plugins enable`	Enable one plugin
`godot-cli project plugins disable`	Disable one plugin
`godot-cli project plugins apply`	Apply plugin intent JSON (enable/disable lists)
`godot-cli project plugins validate`	Validate enabled plugin paths exist
`godot-cli project rendering`	Rendering method and graphics driver settings
`godot-cli project rendering list`	List [rendering] section settings
`godot-cli project rendering apply`	Apply rendering intent JSON (friendly aliases)
`godot-cli project rendering validate`	Validate known rendering method/driver values
`godot-cli project physics`	Physics engine and gravity settings
`godot-cli project physics list`	List [physics] section settings
`godot-cli project physics apply`	Apply physics intent JSON (friendly aliases)
`godot-cli project physics validate`	Validate known physics engine and scalar values
`godot-cli completions`	Print shell completions (bash, zsh, fish)
`godot-cli man`	Print the godot-cli(1) man page in roff format
`godot-cli reference`	Print the command reference as Markdown or JSON
`godot-cli mcp`	Serve the commands as MCP tools over stdio

Commands

`godot-cli help`

Show help for a command

godot-cli help

`godot-cli ping`

Framework health check

Returns a trivial response so callers can verify JSON and CLI wiring.

godot-cli ping

`godot-cli uid`

Godot-compatible resource and scene ID helpers

godot-cli uid [options]

Subcommands

Subcommand	Summary
`encode`	Encode a numeric Resource UID to uid:// text
`decode`	Decode uid:// text to a numeric Resource UID
`create-for-path`	The UID Godot would assign a new file (to read a file's existing UID, use uid read)
`read`	Read the UID a file records, from the file itself
`scene-id`	Scene-local 5-character unique id helpers
`cache`	Inspect project uid_cache.bin
`session`	Persistent ext_resource id session cache

`godot-cli uid encode`

Encode a numeric Resource UID to uid:// text

Converts a 63-bit integer to Godot's uid:// representation.

godot-cli uid encode <id>

Arguments

Argument	Description
`<id>`	Numeric UID to encode

`godot-cli uid decode`

Decode uid:// text to a numeric Resource UID

The number comes back as a decimal string, not a JSON number: a UID is 63 bits, far past the 53 a JSON parser that reads numbers as doubles can hold, JavaScript's included, so such a parser would round it. Store it as a signed 64-bit integer or as text.

godot-cli uid decode <uid>

Arguments

Argument	Description
`<uid>`	uid:// text to decode

`godot-cli uid create-for-path`

The UID Godot would assign a new file (to read a file's existing UID, use uid read)

Matches ResourceUID.create_id_for_path using project name, Godot resource path, and file bytes: the UID Godot would assign a file that has none. To find the UID a file already has, use uid read; a binary resource's never equals this. Result data: uid, and id as a decimal string, since a 63-bit number does not survive a JSON parser that reads numbers as doubles.

godot-cli uid create-for-path [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--project-name`	`<value>`	Project application/config/name	—
`--resource-path`	`<value>`	Godot path e.g. res://main.tscn	—

`godot-cli uid read`

Read the UID a file records, from the file itself

Needs no uid_cache.bin, so it works on a fresh clone. A scene or resource keeps its UID in its own header, binary (.res, .scn) or text (.tscn, .tres); a script keeps it in a .uid sidecar and an imported asset in its .import file. Fails with no_uid_recorded when the file records none. Result data: path, uid, source (text_header, binary_header, uid_sidecar or import_file), and for a binary resource its class, compressed, godot_version and format_version.

godot-cli uid read <file>

Arguments

Argument	Description
`<file>`	Project file: a scene or resource (.tscn, .tres, .scn, .res), a script, or an imported asset

`godot-cli uid scene-id`

Scene-local 5-character unique id helpers

godot-cli uid scene-id [options]

Subcommands

Subcommand	Summary
`generate`	Generate scene unique ids with a deterministic seed

`godot-cli uid scene-id generate`

Generate scene unique ids with a deterministic seed

godot-cli uid scene-id generate [options]

Options

Option	Value	Description	Default
`--seed`	`<value>`	32-bit seed (e.g. path.hash() from Godot)	—
`--count`	`<value>`	Number of ids to generate (default 1)	—

`godot-cli uid cache`

Inspect project uid_cache.bin

godot-cli uid cache [options]

Subcommands

Subcommand	Summary
`list`	List all UID cache entries
`lookup`	Resolve uid:// text to path or path to uid:// text

`godot-cli uid cache list`

List all UID cache entries

godot-cli uid cache list [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli uid cache lookup`

Resolve uid:// text to path or path to uid:// text

godot-cli uid cache lookup [options] <query>

Arguments

Argument	Description
`<query>`	res:// path or uid:// text to look up

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli uid session`

Persistent ext_resource id session cache

godot-cli uid session [options]

Subcommands

Subcommand	Summary
`import`	Import ext_resource ids from a Godot-saved scene

`godot-cli uid session import`

Import ext_resource ids from a Godot-saved scene

Updates scene_id_cache.json so future saves reuse Godot-assigned ext_resource ids.

godot-cli uid session import [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--referrer`	`<value>`	Referrer res:// path (scene being saved)	—
`--from`	`<path>`	Godot-saved scene to import ids from	—
`--id-session`	`<path>`	Session cache JSON path	—
`--project-root`	`<path>`	Godot project root (default session path under .godot/)	—

`godot-cli scene`

Inspect and edit Godot scene files

godot-cli scene [options]

Subcommands

Subcommand	Summary
`new`	Create a new empty scene file
`describe`	Everything about a scene in one call: nodes with properties, connections, references, scripts
`refs`	List ext_resource references in a scene
`ext`	Add or remove external resources
`sub`	Add or remove sub-resources
`inspect`	Parse a .tscn file and report structure and ID issues
`node`	List and query scene node tree
`connection`	Signal connections stored in the scene ([connection] sections)
`extract`	Move a subtree into its own scene and instance it back in place
`instance`	Add instanced PackedScene nodes
`template`	Built-in scene templates for scaffolding
`recipes`	List the intent recipes and the fields each takes
`plan`	Expand intent JSON to a patch and preview (no write)
`apply`	Apply a declarative JSON patch to a scene
`diff`	Compare node trees between two scenes
`restore`	Restore a scene from a snapshot file
`validate`	Validate scene IDs and references (fails on errors)
`validate-batch`	Validate multiple scene files (aggregated JSON, exit 1 on any error)
`set-property`	Set a property on a node section and save the scene
`normalize`	Repair scene-local IDs and sort ext_resource sections for save
`retarget-ext`	Replace ext_resource paths across one or more files
`round-trip`	Parse and rewrite a scene; fail if structure is not preserved
`compare-godot`	Compare a scene to a Godot headless save (semantic match)

`godot-cli scene new`

Create a new empty scene file

Writes a minimal gd_scene with a single root node. Use scene node add to build the tree.

godot-cli scene new [options]

Options

Option	Value	Description	Default
`--output`	`<path>`	Output .tscn path (required) (required)	—
`--root-name`	`<value>`	Scene root node name (default: Root)	—
`--root-type`	`<value>`	Scene root node type (default: Node)	—
`--no-uid`	—	Do not stamp a uid="uid://..." on the header	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene describe`

Everything about a scene in one call: nodes with properties, connections, references, scripts

The tree with each node's properties, instanced nodes resolved to the class they really are (with --project-root), the [connection] sections, every external reference with whether it resolves, and the scripts attached to nodes. Replaces the node list, inspect, connection list, refs and node get calls a caller would otherwise make to learn one scene before changing it.

godot-cli scene describe [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (optional): resolves an instanced node to its scene's root class; the file is read either way	—

`godot-cli scene refs`

List ext_resource references in a scene

With a project root, resolves res:// paths to filesystem paths and reports whether each file exists.

godot-cli scene refs [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for uid_cache lookup and res:// seed path	—

`godot-cli scene ext`

Add or remove external resources

godot-cli scene ext [options]

Subcommands

Subcommand	Summary
`add`	Add an ext_resource section
`remove`	Remove an ext_resource by id

`godot-cli scene ext add`

Add an ext_resource section

Inserts before node sections and assigns a Godot-style id (e.g. 1_ab12c).

godot-cli scene ext add [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--type`	`<value>`	Godot resource type (e.g. Script, PackedScene) (required)	—
`--path`	`<value>`	Godot res:// path for the external resource (required)	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene ext remove`

Remove an ext_resource by id

Takes the scene path and the resource id (e.g. 1_abc12). Fails with referrer list if the id is still referenced in property text.

godot-cli scene ext remove [options] <file> <id>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`<id>`	Resource id as written in the file, e.g. CapsuleShape2D_abc12

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene sub`

Add or remove sub-resources

godot-cli scene sub [options]

Subcommands

Subcommand	Summary
`add`	Add a sub_resource section
`remove`	Remove a sub_resource by id

`godot-cli scene sub add`

Add a sub_resource section

Inserts before node sections and assigns a Godot-style id (e.g. CapsuleShape3D_ab12c).

godot-cli scene sub add [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--type`	`<value>`	Godot resource class (e.g. RectangleShape2D) (required)	—
`--property`	`<value>`	Property to set on the new resource; repeat with --value for several	—
`--value`	`<value>`	Property value (Variant text), one per --property	—
`--properties`	`<value>`	JSON object of property name to value, instead of or as well as --property/--value; where both set one property, this object wins. Numbers and booleans are JSON; a string is Variant text and carries its own quotes ("text": "\"Score\""), and a constructor is its text with no extra quotes ("position": "Vector2(3, 0)", "mesh": "ExtResource(\"2_rock\")")	—
`--raw-value`	—	Write property value verbatim	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene sub remove`

Remove a sub_resource by id

Takes the scene path and the resource id (e.g. 1_abc12). Fails with referrer list if the id is still referenced in property text.

godot-cli scene sub remove [options] <file> <id>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`<id>`	Resource id as written in the file, e.g. CapsuleShape2D_abc12

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene inspect`

Parse a .tscn file and report structure and ID issues

Reads section headers, parsed properties (with --json), and runs ID validation. With a project root, uids are checked against uid_cache.bin.

godot-cli scene inspect [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for uid_cache lookup and res:// seed path	—
`--no-validate`	—	Skip ID validation	—
`--parse-properties`	—	Include parsed property values in JSON output	—
`--no-parse-properties`	—	Omit parsed properties (faster for large files)	—

`godot-cli scene node`

List and query scene node tree

godot-cli scene node [options]

Subcommands

Subcommand	Summary
`list`	List all nodes in a scene with paths and section lines
`get`	Get one node by viewport path or by name
`add`	Add a child node under a parent path
`remove`	Remove a node by viewport path
`rename`	Rename a node and rewrite descendant parent attributes
`reparent`	Move a node under a new parent path

`godot-cli scene node list`

List all nodes in a scene with paths and section lines

godot-cli scene node list [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (optional): resolves an instanced node to its scene's root class; the file is read either way	—

`godot-cli scene node get`

Get one node by viewport path or by name

Pass file and node path (e.g. /root/Root/Player), or use --node-name with optional --parent.

godot-cli scene node get [options] <file> [node]

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`[node]`	Node by viewport path; omit when using --node-name (optional)

Options

Option	Value	Description	Default
`--node-name`	`<value>`	Node name to look up (alternative to node path positional)	—
`--parent`	`<value>`	Parent attribute filter when using --node-name (e.g. "." or "Root")	—
`--project-root`	`<path>`	Godot project root (optional; ignored for file-only reads)	—

`godot-cli scene node add`

Add a child node under a parent path

Requires --parent, --name, and --type. Assigns unique_id on save via save preparation. With --dry-run, section_text is the exact section a write would add. The unique_id in it is the one the write assigns, because it is seeded from the scene's path, so a write straight after gives the same text.

godot-cli scene node add [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--parent`	`<value>`	Viewport parent path (e.g. /root/Main) (required)	—
`--name`	`<value>`	Node name (required)	—
`--type`	`<value>`	Godot node class name (e.g. CharacterBody2D) (required)	—
`--property`	`<value>`	Property to set on the new node; repeat with --value for several	—
`--value`	`<value>`	Property value (Variant text), one per --property	—
`--properties`	`<value>`	JSON object of property name to value, instead of or as well as --property/--value; where both set one property, this object wins. Numbers and booleans are JSON; a string is Variant text and carries its own quotes ("text": "\"Score\""), and a constructor is its text with no extra quotes ("position": "Vector2(3, 0)", "mesh": "ExtResource(\"2_rock\")")	—
`--raw-value`	—	Write property value verbatim	—
`--unique-name`	—	Set unique_name_in_owner on the new node (Access as Unique Name / %Name)	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene node remove`

Remove a node by viewport path

Takes the scene path and the node's viewport path (e.g. /root/Main/Player). Fails if the node has children unless --recursive is set.

godot-cli scene node remove [options] <file> <node>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`<node>`	Node by viewport path, e.g. /root/Main/Player

Options

Option	Value	Description	Default
`--recursive`	—	Remove descendant nodes as well	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene node rename`

Rename a node and rewrite descendant parent attributes

Takes the scene path and the node's viewport path: scene node rename main.tscn /root/Main/Player --name Hero. Connections from or to the node follow the rename.

godot-cli scene node rename [options] <file> <node>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`<node>`	Node by viewport path, e.g. /root/Main/Player

Options

Option	Value	Description	Default
`--name`	`<value>`	New node name (required)	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene node reparent`

Move a node under a new parent path

Takes the scene path and the node's viewport path: scene node reparent main.tscn /root/Main/Player/Camera --parent /root/Main. The node becomes the new parent's last child, as in the editor.

godot-cli scene node reparent [options] <file> <node>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`<node>`	Node by viewport path, e.g. /root/Main/Player

Options

Option	Value	Description	Default
`--parent`	`<value>`	New parent, viewport path (e.g. /root/Main) (required)	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene connection`

Signal connections stored in the scene ([connection] sections)

The editor's Node dock writes a [connection] section per connected signal. These commands read and write the same sections, so a button wired here shows connected in the editor and needs no _ready() code.

godot-cli scene connection [options]

Subcommands

Subcommand	Summary
`list`	List signal connections with from/to as viewport paths
`add`	Connect a signal from one node to a method on another
`remove`	Remove a signal connection

`godot-cli scene connection list`

List signal connections with from/to as viewport paths

godot-cli scene connection list [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (optional): resolves an instanced node to its scene's root class; the file is read either way	—

`godot-cli scene connection add`

Connect a signal from one node to a method on another

Both nodes must exist. Fails with DuplicateConnection if the same signal, nodes, and method are already connected.

godot-cli scene connection add [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--from`	`<value>`	Emitting node, viewport path (e.g. /root/Main/Menu/Resume) (required)	—
`--signal`	`<value>`	Signal name (e.g. pressed) (required)	—
`--to`	`<value>`	Receiving node, viewport path (required)	—
`--method`	`<value>`	Method on the receiving node's script (e.g. _on_resume_pressed) (required)	—
`--deferred`	—	CONNECT_DEFERRED: call at idle time	—
`--one-shot`	—	CONNECT_ONE_SHOT: disconnect after the first emission	—
`--binds`	`<value>`	Extra arguments as Godot array text, e.g. '["quit"]'	—
`--unbinds`	`<n>`	Number of trailing signal arguments to drop	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene connection remove`

Remove a signal connection

godot-cli scene connection remove [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--from`	`<value>`	Emitting node, viewport path (required)	—
`--signal`	`<value>`	Signal name (required)	—
`--to`	`<value>`	Receiving node, viewport path (required)	—
`--method`	`<value>`	Method name; omit to remove every connection of that signal between the two nodes	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene extract`

Move a subtree into its own scene and instance it back in place

The editor's Save Branch as Scene. The node and its descendants move to --output with their properties and unique ids; resources they use are copied across and pruned from the source when nothing else needs them; connections and editable-children sections inside the subtree move with paths rewritten; a connection that crosses the boundary is dropped and listed in messages, since the parent scene must connect to the instance instead. The source gets an instance of the new scene at the same place. With --catalog-id the new scene is registered as a catalog entry.

godot-cli scene extract [options] <file> <node>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`<node>`	Node by viewport path, e.g. /root/Main/Player

Options

Option	Value	Description	Default
`--editable`	—	Mark the instance left behind as editable, so a connection to a node inside it can be written without re-adding the instance	—
`--retarget-dropped-connections`	—	Re-point a connection whose emitter moved at the new scene's root instead of dropping it; the method it names is then the new root's to implement, and is listed in messages	—
`--tags`	`<value>`	Comma-separated tags for the catalog entry (with --catalog-id)	—
`--when-to-use`	`<value>`	When an agent should reach for the new component (with --catalog-id)	—
`--when-not-to-use`	`<value>`	When an agent should use something else (with --catalog-id)	—
`--output`	`<path>`	Path of the new scene, relative to the project root (becomes res://<output>) (required)	—
`--catalog-id`	`<value>`	Also register the new scene in the project catalog under this id (needs the project root)	—
`--summary`	`<value>`	Catalog summary for the new entry	—
`--no-uid`	—	Do not stamp a uid="uid://..." on the new scene's header	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene instance`

Add instanced PackedScene nodes

godot-cli scene instance [options]

Subcommands

Subcommand	Summary
`add`	Instance a PackedScene under a parent node

`godot-cli scene instance add`

Instance a PackedScene under a parent node

Adds ext_resource type=PackedScene and a node with instance=ExtResource(...). Use --scene or --catalog-id (project entries only). With --dry-run, section_text is the exact section a write would add. The unique_id in it is the one the write assigns, because it is seeded from the scene's path, so a write straight after gives the same text.

godot-cli scene instance add [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--parent`	`<value>`	Viewport parent path (e.g. /root/Main) (required)	—
`--name`	`<value>`	Node name for the new instance (required)	—
`--scene`	`<value>`	PackedScene res:// path to instance	—
`--catalog-id`	`<value>`	Project catalog id (resolves the scene path; needs the project root)	—
`--editable`	—	Mark the instance editable in the parent scene ([editable path=...])	—
`--unique-name`	—	Set unique_name_in_owner on the instance root (%Name from owner scripts)	—
`--properties`	`<value>`	JSON object of property name to value to set on the instance root (anchors, offsets, overrides). Numbers and booleans are JSON; a string is Variant text and carries its own quotes ("text": "\"Score\""), and a constructor is its text with no extra quotes ("position": "Vector2(3, 0)", "mesh": "ExtResource(\"2_rock\")")	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene template`

Built-in scene templates for scaffolding

godot-cli scene template [options]

Subcommands

Subcommand	Summary
`list`	List built-in scene templates
`show`	Show template metadata, node tree, and sections
`copy`	Copy a template to a new scene file

`godot-cli scene template list`

List built-in scene templates

godot-cli scene template list [options]

Options

Option	Value	Description	Default
`--templates-root`	`<path>`	Directory containing built-in templates (default: compile-time templates/)	—
`--content`	—	Include raw .tscn source in template show output	—
`--no-parse-properties`	—	Omit parsed properties from template show sections	—

`godot-cli scene template show`

Show template metadata, node tree, and sections

Like scene inspect + node list for a built-in template. Use --content for raw .tscn text.

godot-cli scene template show [options] <template>

Arguments

Argument	Description
`<template>`	Template id, e.g. 2d/top_down_player

Options

Option	Value	Description	Default
`--templates-root`	`<path>`	Directory containing built-in templates (default: compile-time templates/)	—
`--content`	—	Include raw .tscn source in template show output	—
`--no-parse-properties`	—	Omit parsed properties from template show sections	—

`godot-cli scene template copy`

Copy a template to a new scene file

Requires --output. Optional --rename-node and --set-property apply edits before save preparation.

godot-cli scene template copy [options] <template>

Arguments

Argument	Description
`<template>`	Template id, e.g. 2d/top_down_player

Options

Option	Value	Description	Default
`--templates-root`	`<path>`	Directory containing built-in templates (default: compile-time templates/)	—
`--rename-node`	`<value>`	Rename node(s) after copy: Old:New pairs, comma-separated	—
`--set-property`	`<value>`	Set properties after copy: path/prop=value or path\|prop\|value, comma-separated	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (required) (required)	—
`--dry-run`	—	Report copy without writing	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene recipes`

List the intent recipes and the fields each takes

The same table scene plan and scene apply expand from, as JSON: name, summary, required and optional fields. Served over MCP as the resource godot-cli://docs/recipes.

godot-cli scene recipes

`godot-cli scene plan`

Expand intent JSON to a patch and preview (no write)

Expands an intent into patch ops and previews them; with a scene path, dry-runs the patch against that scene. Give the document as a file (--intent, --patch) or inline (--intent-json, --patch-json).

An intent is {"steps": [{"recipe": "player_2d", "parent": "/root/Main", "name": "Player"}]}. Recipes: add_node, node_set, assign_ext, connect, instance_catalog, instance_scene, instance_override, catalog_button, player_2d, static_body_2d, camera_2d, camera_3d, place_3d, ui_panel, tilemap_layer, audio_player. Every recipe takes "parent" and "name" except node_set, assign_ext, instance_override, and connect, which address existing nodes by "path" (or "from"/"to"). The fields of each recipe: scene recipes (MCP resource godot-cli://docs/recipes).

A patch is {"ops": [{"op": "node_add", "parent": "/root/Main", "name": "HUD", "type": "CanvasLayer", "properties": {"visible": false}}]}. In a properties object, numbers and booleans are JSON and a string carries its own quotes: "text": "\"Score\"". Full reference: agent_scene_authoring.md, served over MCP as godot-cli://docs/scene-authoring.

godot-cli scene plan [options] [file]

Arguments

Argument	Description
`[file]`	Scene file to dry-run the expanded patch against (optional)

Options

Option	Value	Description	Default
`--intent`	`<path>`	Intent JSON with steps/recipes (expands to patch ops)	—
`--patch`	`<path>`	Existing patch JSON to validate and preview	—
`--intent-json`	`<value>`	The intent itself, instead of a file: {"steps": [{"recipe": "player_2d", "parent": "/root/Main", "name": "Player"}]}; recipe fields: scene recipes	—
`--patch-json`	`<value>`	The patch itself, instead of a file: {"ops": [{"op": "node_add", "parent": "/root/Main", "name": "HUD", "type": "CanvasLayer"}]}	—
`--write-patch`	`<path>`	Write expanded patch JSON to this path	—
`--project-root`	`<path>`	Godot project root for uid_cache lookup and res:// seed path	—

`godot-cli scene apply`

Apply a declarative JSON patch to a scene

Applies a patch, or an intent expanded to one, as a single write; if any op fails the file is untouched. Give the document as a file (--intent, --patch) or inline (--intent-json, --patch-json); preview first with --dry-run, whose preview_sections holds the exact text of every section a write would add or change, in file order and with the unique_ids a write assigns, and preview_diff the change node by node.

An intent is {"steps": [{"recipe": "player_2d", "parent": "/root/Main", "name": "Player"}]}. Recipes: add_node, node_set, assign_ext, connect, instance_catalog, instance_scene, instance_override, catalog_button, player_2d, static_body_2d, camera_2d, camera_3d, place_3d, ui_panel, tilemap_layer, audio_player; their fields: scene recipes (MCP resource godot-cli://docs/recipes). A patch is {"ops": [{"op": "node_add", "parent": "/root/Main", "name": "HUD", "type": "CanvasLayer", "properties": {"visible": false}}]}. In a properties object a string carries its own quotes: "text": "\"Score\"". Full reference: agent_scene_authoring.md, served over MCP as godot-cli://docs/scene-authoring.

godot-cli scene apply [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--patch`	`<path>`	JSON patch file with	—
`--intent-json`	`<value>`	The intent itself, instead of a file: {"steps": [{"recipe": "player_2d", "parent": "/root/Main", "name": "Player"}]}; recipe fields: scene recipes	—
`--patch-json`	`<value>`	The patch itself, instead of a file: {"ops": [{"op": "node_add", "parent": "/root/Main", "name": "HUD", "type": "CanvasLayer"}]}	—
`--intent`	`<path>`	Intent JSON (expands to patch ops via scene plan)	—
`--auto-snapshot`	—	Snapshot the scene before applying, to .godot/godot-cli/snapshots/<its res:// path> under --project-root (beside the scene without one); the result names it	—
`--record-undo`	—	Record undo patch ops in JSON output	—
`--write-undo-patch`	`<path>`	Write undo patch JSON to this path (implies --record-undo)	—
`--no-strict`	—	Continue applying ops after a failure (default: stop on first error)	—
`--preview-properties`	—	With --dry-run, include property-level changes in preview_diff	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene diff`

Compare node trees between two scenes

Reports added, removed, type-changed and unique_id-changed nodes; connections; and ext_resources (keyed by path) and sub_resources (keyed by id) that were added, removed, or changed type or uid. Use --properties for property-level diff: changed properties on nodes in both scenes, every property of a node that was added or removed, and changed properties of a sub_resource, addressed as SubResource("id"). An instanced node's type is its scene's root class when --project-root says where that scene lives, and instance_of then reads PackedScene; without a root its type reads PackedScene. instance_path_a or instance_path_b names the scene.

godot-cli scene diff [options] <a> <b>

Arguments

Argument	Description
`<a>`	First scene file
`<b>`	Second scene file

Options

Option	Value	Description	Default
`--properties`	—	Include node property diffs (added/removed/changed)	—
`--project-root`	`<path>`	Godot project root (optional): resolves an instanced node to its scene's root class; the file is read either way	—

`godot-cli scene restore`

Restore a scene from a snapshot file

Copies --from snapshot over the target scene (full file restore).

godot-cli scene restore [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--from`	`<path>`	Snapshot file to restore from	—
`--snapshot`	`<path>`	Alias for --from	—
`--dry-run`	—	Report restore without writing	—

`godot-cli scene validate`

Validate scene IDs and references (fails on errors)

godot-cli scene validate [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for uid_cache lookup and res:// seed path	—

`godot-cli scene validate-batch`

Validate multiple scene files (aggregated JSON, exit 1 on any error)

godot-cli scene validate-batch [options] <files>...

Arguments

Argument	Description
`<files>...`	One or more scene or resource files

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for uid_cache lookup and res:// seed path	—

`godot-cli scene set-property`

Set a property on a node section and save the scene

Target a node with --node (viewport path) or --node-name, or a section with --section-line. The value is Variant text, normalised the way the editor writes it unless --raw-value.

godot-cli scene set-property [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--property`	`<value>`	Property name to set; repeat with --value for several	—
`--value`	`<value>`	Property value (normalized unless --raw-value), one per --property	—
`--properties`	`<value>`	JSON object of property name to value, instead of or as well as --property/--value; where both set one property, this object wins. Numbers and booleans are JSON; a string is Variant text and carries its own quotes ("text": "\"Score\""), and a constructor is its text with no extra quotes ("position": "Vector2(3, 0)", "mesh": "ExtResource(\"2_rock\")")	—
`--raw-value`	—	Write value verbatim without Variant normalization	—
`--node`	`<value>`	Target node by viewport path (e.g. /root/Main/Player)	—
`--node-name`	`<value>`	Target node section by name attribute	—
`--section-id`	`<value>`	Target an ext_resource or sub_resource by its id (e.g. CapsuleShape2D_abc12)	—
`--section-line`	`<n>`	Target section by header line number	—
`--section`	`<value>`	Target section by tag name (e.g. resource)	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene normalize`

Repair scene-local IDs and sort ext_resource sections for save

Runs Godot-compatible save preparation without editing properties. changed says whether the save changes the file, so --dry-run answers "is this file already written the way a save writes it?"; a dry run also returns preview_sections, the exact text of each section a save would change or add.

godot-cli scene normalize [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene retarget-ext`

Replace ext_resource paths across one or more files

godot-cli scene retarget-ext [options] <files>...

Arguments

Argument	Description
`<files>...`	One or more scene or resource files

Options

Option	Value	Description	Default
`--from`	`<value>`	Current ext_resource path (res://…) (required)	—
`--to`	`<value>`	New ext_resource path (res://…) (required)	—
`--project-root`	`<path>`	Godot project root for res:// seed path	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding	—
`--no-prepare-save`	—	Skip Godot save preparation on write	—
`--output`	`<path>`	Output path when processing a single file	—
`--dry-run`	—	Report changes without writing	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli scene round-trip`

Parse and rewrite a scene; fail if structure is not preserved

godot-cli scene round-trip [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Check structure preservation without writing	—

`godot-cli scene compare-godot`

Compare a scene to a Godot headless save (semantic match)

Compares the node tree (order, headers, unique_id), each node's properties with ext_resource ids read as the paths they name, the ext_resource paths, and the scene's and each ext_resource's uid wherever both files carry one. Not compared: ext_resource ids, which Godot renumbers; load_steps; and sub_resources, whose default fields Godot drops. On a mismatch, difference names the first one. The Godot save is the second positional, or --reference, the same thing. project resave makes one.

godot-cli scene compare-godot [options] <file> [saved]

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`[saved]`	Godot-saved file to compare against; or pass --reference (optional)

Options

Option	Value	Description	Default
`--reference`	`<path>`	Godot-saved reference file (default: second positional)	—

`godot-cli resource`

Inspect and edit Godot resource files

godot-cli resource [options]

Subcommands

Subcommand	Summary
`new`	Create a new .tres resource file
`sub`	Sub-resources embedded in a .tres
`ext`	External resource references in a .tres
`inspect`	Parse a .tres file and report structure and ID issues
`validate`	Validate resource IDs and references (fails on errors)
`validate-batch`	Validate multiple resource files (aggregated JSON, exit 1 on any error)
`set-property`	Set a property on a resource section and save
`normalize`	Repair scene-local IDs and sort ext_resource sections for save
`retarget-ext`	Replace ext_resource paths across one or more files
`round-trip`	Parse and rewrite a resource file; fail if structure is not preserved
`compare-godot`	Compare a resource to a Godot headless save (semantic match)

`godot-cli resource new`

Create a new .tres resource file

Writes a gd_resource header and a [resource] section. Repeat --property/--value for several properties. Add sub-resources with resource sub add and external files with resource ext add.

godot-cli resource new [options]

Options

Option	Value	Description	Default
`--output`	`<path>`	Output .tres path (required) (required)	—
`--type`	`<value>`	Resource class (e.g. StandardMaterial3D, Theme, RectangleShape2D) (required)	—
`--property`	`<value>`	Property to set on the resource; repeat with --value for several	—
`--value`	`<value>`	Property value (Variant text), one per --property	—
`--properties`	`<value>`	JSON object of property name to value, instead of or as well as --property/--value; where both set one property, this object wins. Numbers and booleans are JSON; a string is Variant text and carries its own quotes ("text": "\"Score\""), and a constructor is its text with no extra quotes ("position": "Vector2(3, 0)", "mesh": "ExtResource(\"2_rock\")")	—
`--raw-value`	—	Write property values verbatim	—
`--no-uid`	—	Do not stamp a uid="uid://..." on the header	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli resource sub`

Sub-resources embedded in a .tres

godot-cli resource sub [options]

Subcommands

Subcommand	Summary
`add`	Add a sub_resource; reference it as SubResource("<id>")
`remove`	Remove a sub_resource by id

`godot-cli resource sub add`

Add a sub_resource; reference it as SubResource("<id>")

godot-cli resource sub add [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--type`	`<value>`	Godot resource class (e.g. StyleBoxFlat) (required)	—
`--property`	`<value>`	Property to set on the new sub-resource; repeat with --value for several	—
`--value`	`<value>`	Property value (Variant text), one per --property	—
`--properties`	`<value>`	JSON object of property name to value, instead of or as well as --property/--value; where both set one property, this object wins. Numbers and booleans are JSON; a string is Variant text and carries its own quotes ("text": "\"Score\""), and a constructor is its text with no extra quotes ("position": "Vector2(3, 0)", "mesh": "ExtResource(\"2_rock\")")	—
`--raw-value`	—	Write property values verbatim	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli resource sub remove`

Remove a sub_resource by id

Takes the file path and the resource id. Fails with referrer list if the id is still referenced.

godot-cli resource sub remove [options] <file> <id>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`<id>`	Resource id as written in the file, e.g. CapsuleShape2D_abc12

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli resource ext`

External resource references in a .tres

godot-cli resource ext [options]

Subcommands

Subcommand	Summary
`add`	Register an external file; reference it as ExtResource("<id>")
`remove`	Remove an ext_resource by id

`godot-cli resource ext add`

godot-cli resource ext add [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--type`	`<value>`	Resource type of the external file (e.g. Texture2D, Script) (required)	—
`--path`	`<value>`	res:// path of the external file (required)	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli resource ext remove`

Remove an ext_resource by id

Takes the file path and the resource id. Fails with referrer list if the id is still referenced.

godot-cli resource ext remove [options] <file> <id>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`<id>`	Resource id as written in the file, e.g. CapsuleShape2D_abc12

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli resource inspect`

Parse a .tres file and report structure and ID issues

Reads section headers, parsed properties (with --json), and runs ID validation.

godot-cli resource inspect [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for uid_cache lookup and res:// seed path	—
`--no-validate`	—	Skip ID validation	—
`--parse-properties`	—	Include parsed property values in JSON output	—
`--no-parse-properties`	—	Omit parsed properties (faster for large files)	—

`godot-cli resource validate`

Validate resource IDs and references (fails on errors)

godot-cli resource validate [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for uid_cache lookup and res:// seed path	—

`godot-cli resource validate-batch`

Validate multiple resource files (aggregated JSON, exit 1 on any error)

godot-cli resource validate-batch [options] <files>...

Arguments

Argument	Description
`<files>...`	One or more scene or resource files

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for uid_cache lookup and res:// seed path	—

`godot-cli resource set-property`

Set a property on a resource section and save

godot-cli resource set-property [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--property`	`<value>`	Property name to set	—
`--value`	`<value>`	Property value (normalized unless --raw-value)	—
`--raw-value`	—	Write value verbatim without Variant normalization	—
`--section-line`	`<n>`	Target section by header line number	—
`--section`	`<value>`	Target section by tag name (default: resource)	—
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli resource normalize`

Repair scene-local IDs and sort ext_resource sections for save

godot-cli resource normalize [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root for res:// seed path and id session cache	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding (overrides the project root)	—
`--no-prepare-save`	—	Skip Godot save preparation (ID repair/sort)	—
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Parse and validate edit without writing	—
`--snapshot`	`<path>`	Before writing, copy the file as it is now to this path, for scene diff or scene restore later. Put it under .godot/: a copy Godot can see carries the scene's uid, and Godot then reports a duplicate and may point uid:// references at the copy. Nothing under .godot/ is imported, and it is normally gitignored	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli resource retarget-ext`

Replace ext_resource paths across one or more files

godot-cli resource retarget-ext [options] <files>...

Arguments

Argument	Description
`<files>...`	One or more scene or resource files

Options

Option	Value	Description	Default
`--from`	`<value>`	Current ext_resource path (res://…)	—
`--to`	`<value>`	New ext_resource path (res://…)	—
`--project-root`	`<path>`	Godot project root for res:// seed path	—
`--resource-path`	`<value>`	Godot res:// path for ID seeding	—
`--no-prepare-save`	—	Skip Godot save preparation on write	—
`--output`	`<path>`	Output path when processing a single file	—
`--dry-run`	—	Report changes without writing	—
`--id-session`	`<path>`	Path to ext_resource id session cache JSON	—
`--no-id-session`	—	Do not load or update ext_resource id session cache	—
`--godot-save-format`	—	Strip Godot-omitted header fields and default sub_resource properties	—
`--normalize-properties`	—	Rewrite property values through Variant parse/format	—

`godot-cli resource round-trip`

Parse and rewrite a resource file; fail if structure is not preserved

godot-cli resource round-trip [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--output`	`<path>`	Output path (default: overwrite input)	—
`--dry-run`	—	Check structure preservation without writing	—

`godot-cli resource compare-godot`

Compare a resource to a Godot headless save (semantic match)

A resource has no node tree, so this compares only its ext_resource paths and the uids both files carry; the [resource] and sub_resource sections are not compared. On a mismatch, difference names it. The Godot save is the second positional, or --reference, the same thing.

godot-cli resource compare-godot [options] <file> [saved]

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)
`[saved]`	Godot-saved file to compare against; or pass --reference (optional)

Options

Option	Value	Description	Default
`--reference`	`<path>`	Godot-saved reference file (default: second positional)	—

`godot-cli catalog`

Project component catalog

Create, scan, list, show, validate, search, and export catalog manifests describing project components for LLM agents.

godot-cli catalog [options]

Subcommands

Subcommand	Summary
`add`	Create or update a JSON catalog manifest for a scene
`relink`	Repoint manifests whose scene has moved
`scan`	Scan project for catalog manifests
`list`	List valid catalog entries
`show`	Show merged catalog entry by id
`validate`	Validate catalog manifests in a project
`search`	Search project catalog entries and builtins
`export`	Export agent digest markdown

`godot-cli catalog add`

Create or update a JSON catalog manifest for a scene

Writes <scene>.manifest.json beside the scene, filling scene_uid from the scene header and scaffolding a row for each signal declared by the root script. With --update, prose already written is preserved.

godot-cli catalog add [options] <file>

Arguments

Argument	Description
`<file>`	Scene file (.tscn)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--id`	`<value>`	Catalog id (default: scene path without res:// and extension)	—
`--summary`	`<value>`	One-line description of the component	—
`--when-to-use`	`<value>`	When an agent should reach for this component	—
`--when-not-to-use`	`<value>`	When an agent should use something else	—
`--notes`	`<value>`	Edge cases and variant notes	—
`--tags`	`<value>`	Comma-separated tags	—
`--signal-doc`	`<value>`	Document a signal the root script declares: <signal>=<what it means>; repeatable, and fills the row catalog add scaffolds	—
`--export-doc`	`<value>`	Document an @export the root script declares: <property>=<what setting it does>; repeatable, and fills the row catalog add scaffolds	—
`--function-doc`	`<value>`	Document a method callers are meant to use: <function>=<what it does>; repeatable. Not scaffolded, since the script parse reads exports and signals but not functions	—
`--related-ids`	`<value>`	Comma-separated related catalog ids	—
`--prefer-over-ids`	`<value>`	Comma-separated catalog ids this component should be chosen over	—
`--export-root-script`	`<value>`	res:// script to read exports and signals from, when they are not on the root node's own script	—
`--update`	—	Update an existing manifest, keeping prose already written	—
`--output`	`<path>`	Manifest path (default: <scene>.manifest.json beside the scene)	—
`--dry-run`	—	Render the manifest without writing it	—

`godot-cli catalog relink`

Repoint manifests whose scene has moved

For every manifest whose scene file is missing, resolves its scene_uid through .godot/uid_cache.bin and rewrites the scene path. Requires the project to have been opened in Godot since the move, since the editor is what refreshes that cache. Exits 1 if any manifest is still unrepaired.

godot-cli catalog relink [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--dry-run`	—	Report which manifests would be repointed without writing them	—

`godot-cli catalog scan`

Scan project for catalog manifests

Walks the project for *.manifest.json, parses fields, and validates catalog entries.

godot-cli catalog scan [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli catalog list`

List valid catalog entries

Runs catalog scan and returns valid entries only (id, scene, summary, tags).

godot-cli catalog list [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli catalog show`

Show merged catalog entry by id

Returns manifest fields merged with scene nodes and GDScript exports/signals. Builtin ids use the godot/ namespace.

godot-cli catalog show [options] <id>

Arguments

Argument	Description
`<id>`	Catalog entry id, e.g. ui/button

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli catalog validate`

Validate catalog manifests in a project

Runs catalog scan and fails when any manifest has validation errors.

godot-cli catalog validate [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli catalog search`

Search project catalog entries and builtins

Filter by tags and/or free-text query across summaries and documentation fields.

godot-cli catalog search [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--tags`	`<value>`	Comma-separated tag filter (all tags must match)	—
`--query`	`<value>`	Free-text search across summaries and docs	—

`godot-cli catalog export`

Export agent digest markdown

Writes a markdown catalog digest for LLM agents (default: AGENTS.md in the project root).

godot-cli catalog export [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--output`	`<path>`	Output markdown path relative to project root (default: AGENTS.md)	—
`--dry-run`	—	Generate markdown without writing the output file	—

`godot-cli batch`

Run multiple CLI commands in one invocation

Each step is a full argv array. Modes: stop (default), continue, atomic. See docs/agent_batch_commands.md.

godot-cli batch [options]

Options

Option	Value	Description	Default
`--file`	`<path>`	Batch JSON file with mode, rollback, and steps	—
`--json-body`	`<value>`	Batch JSON inline (use --file if your shell conflicts with global --request)	—

`godot-cli project`

Read and write Godot project.godot settings

Project-level configuration: input, autoloads, plugins, rendering, physics, display, layer names.

godot-cli project [options]

Subcommands

Subcommand	Summary
`new`	Create a project.godot in a new or empty folder
`import`	Run Godot's headless import so new files get UIDs and .import data
`resave`	Have Godot load a scene or resource and save a copy, the reference for compare-godot
`run`	Run the game for a few frames and capture the last frame and the log
`show`	Summarize key project.godot configuration
`move`	Move or rename a file and repoint every reference to it
`apply`	Apply unified project intent JSON (input, settings, autoload, plugins, rendering, physics)
`input`	Input Map actions in project.godot
`settings`	Scalar project settings (application, display, layer_names, …)
`autoload`	Autoload singletons in project.godot
`plugins`	Editor plugins enable/disable in project.godot
`rendering`	Rendering method and graphics driver settings
`physics`	Physics engine and gravity settings

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project new`

Create a project.godot in a new or empty folder

Writes the header the project manager writes, config_version=5, and [application] config/name, plus the main scene and window size when given. Refuses to overwrite an existing project.godot; change that with project settings set or project apply.

godot-cli project new [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Folder to create the project in (default: current directory)	—
`--name`	`<value>`	Project name (application/config/name) (required)	—
`--main-scene`	`<value>`	Main scene as a res:// path (application/run/main_scene)	—
`--width`	`<n>`	Viewport width in pixels (display/window/size/viewport_width)	—
`--height`	`<n>`	Viewport height in pixels (display/window/size/viewport_height)	—
`--dry-run`	—	Report what would be written without creating the file	—
`--no-icon`	—	Do not write the default icon.svg beside project.godot	—

`godot-cli project import`

Run Godot's headless import so new files get UIDs and .import data

godot --headless --path . --import --quit, from the project root. Run it once after adding scenes, scripts, or textures, before running the game or filling catalog scene_uid fields. Godot writes into the project as it imports: a .import file beside each asset, a .uid file beside each script, and the .godot/ folder, which holds the uid cache. Commit the .import and .uid files: a UID is assigned once and kept there, and if the file changes later, a checkout without them would be assigned a different one.

godot-cli project import [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (default: current directory)	—
`--godot`	`<path>`	Godot binary; default $GODOT, then godot on PATH, then the macOS app bundle	—

`godot-cli project resave`

Have Godot load a scene or resource and save a copy, the reference for compare-godot

Imports (unless --no-import), then runs Godot headless to load the file and save a copy to --output, by default .godot/godot-cli/resave/<its path>, where Godot imports nothing. Never over the file itself. The copy is Godot's own writing of the file's content, so scene compare-godot <file> <copy> checks the file against it. That check is semantic, not byte for byte: saved to a new path, the copy's ext_resource ids are renumbered and its uids left out, so compare-godot leaves those out of the comparison, and scene validate checks uids against the files. A byte-for-byte check would need Godot to save over the file, which this never does. The driver script it runs is written to .godot/godot-cli/resave.gd. Result data: file, output, output_path, exit, summary.

godot-cli project resave [options] <file>

Arguments

Argument	Description
`<file>`	Scene or resource file (.tscn or .tres)

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (default: current directory)	—
`--godot`	`<path>`	Godot binary; default $GODOT, then godot on PATH, then the macOS app bundle	—
`--output`	`<value>`	Where the copy goes, res:// or project-relative; default .godot/godot-cli/resave/<the file's path>, where Godot imports nothing	—
`--no-import`	—	Skip the import that runs first; a project never imported cannot load its textures	—

`godot-cli project run`

Run the game for a few frames and capture the last frame and the log

Imports (unless --no-import; the import writes .import and .uid files into the project, as project import says), then runs the main scene or --scene with --write-movie into the capture folder (--capture-dir, under .godot/ by default, which Godot never imports), quits after --frames, and reads the log. The result names the last frame, the log and its last 40 lines, and every ERROR or SCRIPT ERROR line with its backtrace; it fails (exit 1) when Godot did not exit cleanly or the log holds an error, so the change is not done until this passes. A run can pass with a wrong layout, so read the frame as well as the log. --press move_right@10..40 holds an input action over a frame range and --click /root/Main/HUD/PauseButton@20 clicks a node, so movement and buttons can be exercised; the frame then shows the result. The cursor moves off the node after a click, so the last frame shows its normal style; --keep-cursor leaves it there for the hover style. Only the game's own cursor moves, never the desktop pointer. Result data: frame (path of the last PNG), log, log_tail (last 40 lines), errors and error_count, exit and import_exit, stderr_tail, frames_written, presses, clicks, duration_ms, summary. Frames other than the last, and the .wav Godot writes, are deleted unless --keep-frames. Over MCP the frame is also returned as an image.

godot-cli project run [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (default: current directory)	—
`--godot`	`<path>`	Godot binary; default $GODOT, then godot on PATH, then the macOS app bundle	—
`--scene`	`<value>`	Scene to run (res:// or project-relative); the main scene when omitted	—
`--frames`	`<n>`	Frames to run before quitting; 60 is one second, 5 is enough for a static screen	`60`
`--resolution`	`<value>`	Window size as WIDTHxHEIGHT; default is the project's display/window/size, else 640x360	—
`--capture-dir`	`<path>`	Folder under the project for the frame and log; the default is under .godot/, which Godot never imports	`.godot/godot-cli`
`--no-import`	—	Skip the headless import pass that assigns UIDs to new files	—
`--keep-frames`	—	Keep every frame and the .wav; the default keeps only the last frame	—
`--headless`	—	No window and no frames, only the log; for machines without a display. --press and --click both work: the run puts the project's viewport size back, which the headless display server does not report. What you lose is the frame	—
`--user-arg`	`<value>`	Argument passed after --, readable with OS.get_cmdline_user_args(); repeatable	—
`--press`	`<value>`	Hold an input action over a frame range, e.g. move_right@10..40 or ui_accept@5; repeatable. Sent as a real InputEventAction and as polled action state, so a focused Control and Input.get_vector both see it	—
`--click`	`<value>`	Left-click the centre of a node on a frame, e.g. /root/Main/HUD/PauseButton@20; repeatable. A Button's pressed signal fires from this, and the cursor moves off the node after the release so later frames show its normal style. Works under --headless too. A click on a node laid out beyond the viewport reaches nothing and fails the run rather than passing silently	—
`--type`	`<value>`	Type text into a LineEdit or TextEdit on a frame: <node-path>@<frame>=<text>, e.g. /root/Main/%Email@20=someone@example.com; repeatable. The field is focused and emptied, then the text goes in as real key events, so text_changed fires the way a validating form expects. The value lands the frame after, so click Submit at least two frames later	—
`--focus`	`<value>`	Give a Control keyboard focus on a frame: <node-path>@<frame>; repeatable. --type focuses the field it types into, so this is for watching a focus ring or a tab order	—
`--keep-cursor`	—	Leave the synthetic cursor on the last clicked node instead of moving it off, so the frame shows that node's hover style; only the in-game cursor moves either way, never the desktop pointer	—
`--frame-at`	`<n>`	Also keep this frame (numbered from 0) and return it as frame_at; repeatable, so --frame-at 0 --frame-at 30 keeps a before-and-after pair as well as the last frame	—
`--log-lines`	`<n>`	Lines of the log to return inline as log_tail	`40`

`godot-cli project show`

Summarize key project.godot configuration

godot-cli project show [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project move`

Move or rename a file and repoint every reference to it

Renames the file with its .uid and .import sidecars, rewrites every ext_resource path in the project's scenes and resources, repoints catalog manifests, and updates project.godot settings such as the main scene and autoloads. Paths are res:// or project-relative.

godot-cli project move [options]

Options

Option	Value	Description	Default
`--rename-ids`	—	Re-seed ext_resource ids from the new file name, so a Script_player id stops naming a file called hero.gd; ids already in use are left alone	—
`--godot`	`<path>`	Godot binary; default $GODOT, then godot on PATH, then the macOS app bundle	—
`--import`	—	Run Godot's headless import after the move, so its uid cache stops mapping the old path and validation stops reporting uid_path_mismatch	—
`--from`	`<value>`	Current path (res://scripts/player.gd or scripts/player.gd) (required)	—
`--to`	`<value>`	New path (required)	—
`--dry-run`	—	Report what would change without moving or writing	—
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project apply`

Apply unified project intent JSON (input, settings, autoload, plugins, rendering, physics)

One intent with any of the sections: {"settings": {"application": {"run/main_scene": "res://scenes/main.tscn"}}, "input": {"actions": [{"name": "move_left", "events": [{"type": "key", "keycode": "A", "physical": true}]}]}, "autoload": {"autoloads": [{"name": "GameState", "path": "res://scripts/game_state.gd", "singleton": true}]}, "physics": {"engine_3d": "Jolt Physics"}}. Each section takes the same document as the matching project <section> apply command. Give it as a file (--intent) or inline (--intent-json).

godot-cli project apply [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--intent`	`<path>`	Intent JSON file: settings {"<section>": {"<key>": value}}, input {"actions": [{"name", "events": [{"type": "key", "keycode": "A", "physical": true}]}]}, autoload {"autoloads": [{"name", "path", "singleton"}]}, plugins, rendering, physics; see the examples	—
`--intent-json`	`<value>`	The intent itself, instead of a file; the same document the intent option describes	—
`--file`	`<path>`	Alias for --intent	—
`--dry-run`	—	Apply in memory without writing project.godot	—

`godot-cli project input`

Input Map actions in project.godot

godot-cli project input [options]

Subcommands

Subcommand	Summary
`list`	List input actions
`apply`	Apply input map intent JSON (merge/replace per action)
`validate`	Validate [input] section event objects

`godot-cli project input list`

List input actions

godot-cli project input list [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project input apply`

Apply input map intent JSON (merge/replace per action)

One intent: {"actions": [{"name": "move_left", "deadzone": 0.5, "events": [...]}]}; each action replaces the one of the same name. Event types: {"type": "key", "keycode": <name or number>, "physical": true, "ctrl": false, "shift": false, "alt": false, "meta": false}, {"type": "mouse_button", "button": <name or number>}, {"type": "joypad_button", "button": <name or number>}, {"type": "joypad_motion", "axis": <name or number>, "axis_value": -1.0}. Keys: a letter or digit, space, escape, tab, backtab, backspace, enter/return, kp_enter, insert, delete, pause, print, home, end, left, up, right, down, pageup, pagedown, shift, ctrl, meta/cmd, alt, capslock, numlock, scrolllock, f1-f12; or a Godot keycode number. Names are matched without case, and KEY_<letter> is accepted. Mouse buttons: left, right, middle, wheel_up, wheel_down, wheel_left, wheel_right, xbutton1/x1, xbutton2/x2; or the MouseButton number. Names are matched without case. Joypad buttons: a/south, b/east, x/west, y/north, back/select, guide/home, start, left_stick/l3, right_stick/r3, left_shoulder/lb, right_shoulder/rb, dpad_up, dpad_down, dpad_left, dpad_right, misc1, paddle1-4, touchpad, misc2-6; or the JoyButton number. Names are matched without case. Joypad axes: left_x/LX, left_y/LY, right_x/RX, right_y/RY, trigger_left/LT, trigger_right/RT; or the JoyAxis number. Names are matched without case.

godot-cli project input apply [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--intent`	`<path>`	Intent JSON file: {"actions": [{"name": "move_left", "deadzone": 0.5, "events": [{"type": "key", "keycode": "A", "physical": true}, {"type": "joypad_motion", "axis": "left_x", "axis_value": -1.0}]}]}; each action replaces one of the same name, and deadzone is optional (Godot defaults to 0.5)	—
`--intent-json`	`<value>`	The intent itself, instead of a file; the same document the intent option describes	—
`--file`	`<path>`	Alias for --intent	—
`--dry-run`	—	Apply in memory without writing project.godot	—

`godot-cli project input validate`

Validate [input] section event objects

godot-cli project input validate [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project settings`

Scalar project settings (application, display, layer_names, …)

godot-cli project settings [options]

Subcommands

Subcommand	Summary
`list`	List settings (optional --section filter)
`get`	Get one setting value
`set`	Set one setting value
`apply`	Apply settings intent JSON (per-key merge)
`validate`	Validate res:// paths in settings

`godot-cli project settings list`

List settings (optional --section filter)

godot-cli project settings list [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--section`	`<value>`	Filter to one section (application, display, layer_names, …)	—

`godot-cli project settings get`

Get one setting value

godot-cli project settings get [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--section`	`<value>`	Section name (e.g. application) (required)	—
`--key`	`<value>`	Setting key (e.g. run/main_scene) (required)	—

`godot-cli project settings set`

Set one setting value

godot-cli project settings set [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--section`	`<value>`	Section name (e.g. application) (required)	—
`--key`	`<value>`	Setting key (e.g. run/main_scene) (required)	—
`--value`	`<value>`	Plain value (quoted automatically for strings) (required)	—
`--raw`	—	Store --value verbatim (already Godot-formatted)	—
`--dry-run`	—	Apply in memory without writing project.godot	—

`godot-cli project settings apply`

Apply settings intent JSON (per-key merge)

godot-cli project settings apply [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--intent`	`<path>`	Intent JSON file: {"<section>": {"<key>": value}}, e.g. {"application": {"run/main_scene": "res://scenes/main.tscn"}, "display": {"window/size/viewport_width": 640}}; keys merge into the existing file	—
`--intent-json`	`<value>`	The intent itself, instead of a file; the same document the intent option describes	—
`--file`	`<path>`	Alias for --intent	—
`--dry-run`	—	Apply in memory without writing project.godot	—

`godot-cli project settings validate`

Validate res:// paths in settings

godot-cli project settings validate [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--section`	`<value>`	Filter to one section (application, display, layer_names, …)	—

`godot-cli project autoload`

Autoload singletons in project.godot

godot-cli project autoload [options]

Subcommands

Subcommand	Summary
`list`	List autoload entries
`apply`	Apply autoload intent JSON (merge by name; optional replace_all)
`validate`	Validate autoload paths and names

`godot-cli project autoload list`

List autoload entries

godot-cli project autoload list [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project autoload apply`

Apply autoload intent JSON (merge by name; optional replace_all)

godot-cli project autoload apply [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--intent`	`<path>`	Intent JSON file: {"autoloads": [{"name": "GameState", "path": "res://scripts/game_state.gd", "singleton": true}], "replace_all": false}	—
`--intent-json`	`<value>`	The intent itself, instead of a file; the same document the intent option describes	—
`--file`	`<path>`	Alias for --intent	—
`--dry-run`	—	Apply in memory without writing project.godot	—

`godot-cli project autoload validate`

Validate autoload paths and names

godot-cli project autoload validate [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project plugins`

Editor plugins enable/disable in project.godot

godot-cli project plugins [options]

Subcommands

Subcommand	Summary
`list`	List addons and enabled state
`enable`	Enable one plugin
`disable`	Disable one plugin
`apply`	Apply plugin intent JSON (enable/disable lists)
`validate`	Validate enabled plugin paths exist

`godot-cli project plugins list`

List addons and enabled state

godot-cli project plugins list [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project plugins enable`

Enable one plugin

godot-cli project plugins enable [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--plugin`	`<value>`	Plugin path or addon folder name (res://addons/.../plugin.cfg)	—
`--path`	`<value>`	Alias for --plugin	—
`--dry-run`	—	Apply in memory without writing project.godot	—

`godot-cli project plugins disable`

Disable one plugin

godot-cli project plugins disable [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--plugin`	`<value>`	Plugin path or addon folder name (res://addons/.../plugin.cfg)	—
`--path`	`<value>`	Alias for --plugin	—
`--dry-run`	—	Apply in memory without writing project.godot	—

`godot-cli project plugins apply`

Apply plugin intent JSON (enable/disable lists)

godot-cli project plugins apply [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--intent`	`<path>`	Intent JSON file: {"enable": ["my_addon"], "disable": []}; names are folders under addons/	—
`--intent-json`	`<value>`	The intent itself, instead of a file; the same document the intent option describes	—
`--file`	`<path>`	Alias for --intent	—
`--dry-run`	—	Apply in memory without writing project.godot	—

`godot-cli project plugins validate`

Validate enabled plugin paths exist

godot-cli project plugins validate [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project rendering`

Rendering method and graphics driver settings

godot-cli project rendering [options]

Subcommands

Subcommand	Summary
`list`	List [rendering] section settings
`apply`	Apply rendering intent JSON (friendly aliases)
`validate`	Validate known rendering method/driver values

`godot-cli project rendering list`

List [rendering] section settings

godot-cli project rendering list [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project rendering apply`

Apply rendering intent JSON (friendly aliases)

godot-cli project rendering apply [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--intent`	`<path>`	Intent JSON file: {"method": "forward_plus" \| "mobile" \| "gl_compatibility", "driver": "vulkan" \| "d3d12" \| "metal" \| "opengl3"}, or raw rendering/ keys	—
`--intent-json`	`<value>`	The intent itself, instead of a file; the same document the intent option describes	—
`--file`	`<path>`	Alias for --intent	—
`--dry-run`	—	Apply in memory without writing project.godot	—

`godot-cli project rendering validate`

Validate known rendering method/driver values

godot-cli project rendering validate [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project physics`

Physics engine and gravity settings

godot-cli project physics [options]

Subcommands

Subcommand	Summary
`list`	List [physics] section settings
`apply`	Apply physics intent JSON (friendly aliases)
`validate`	Validate known physics engine and scalar values

`godot-cli project physics list`

List [physics] section settings

godot-cli project physics list [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli project physics apply`

Apply physics intent JSON (friendly aliases)

godot-cli project physics apply [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—
`--intent`	`<path>`	Intent JSON file:	—
`--intent-json`	`<value>`	The intent itself, instead of a file; the same document the intent option describes	—
`--file`	`<path>`	Alias for --intent	—
`--dry-run`	—	Apply in memory without writing project.godot	—

`godot-cli project physics validate`

Validate known physics engine and scalar values

godot-cli project physics validate [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project root (directory containing project.godot)	—

`godot-cli completions`

Print shell completions (bash, zsh, fish)

Generated from the command tree, so completions stay in step with the binary that printed them.

bash: godot-cli completions bash > ~/.godot-cli/share/completions/godot-cli.bash zsh: godot-cli completions zsh > "${fpath[1]}/_godot-cli" fish: godot-cli completions fish > ~/.config/fish/completions/godot-cli.fish

godot-cli completions [options]

Options

Option	Value	Description	Default
`--output`	`<path>`	Write to this file instead of stdout	—

`godot-cli man`

Print the godot-cli(1) man page in roff format

Render with: godot-cli man | man -l -

godot-cli man [options]

Options

Option	Value	Description	Default
`--output`	`<path>`	Write to this file instead of stdout	—

`godot-cli reference`

Print the command reference as Markdown or JSON

--format markdown (default) prints the document committed as docs/commands.md. --format json prints the whole command surface — every command, option, and value kind — for tools that wrap the CLI.

godot-cli reference [options]

Options

Option	Value	Description	Default
`--output`	`<path>`	Write to this file instead of stdout	—
`--format`	`<value>`	markdown or json	`markdown`

`godot-cli mcp`

Serve the commands as MCP tools over stdio

Speaks the Model Context Protocol on stdin and stdout so Claude Code, Cursor, and OpenCode can call every command as a tool, read the agent docs as resources, and start a session from the godot-scene-session prompt. With --project-root the server works inside that project: --project-root . is added to every call and path arguments may not leave it.

claude mcp add godot-cli -- godot-cli mcp --project-root .

godot-cli mcp [options]

Options

Option	Value	Description	Default
`--project-root`	`<path>`	Godot project to serve; injected into every call and enforced on path arguments	—
`--all-options`	—	Also expose the save-preparation and id-session options in the tool schemas	—
`--toolset`	`<value>`	Which tools to serve: all (default), or core for the thirteen that cover most sessions, for a client that loads every schema up front	—

Exit codes

Code	Meaning
`0`	Success
`1`	Runtime or command failure
`2`	Usage or invocation error

Edit this page on GitHub