Command groups

Invocation is swallowtail <group> <command> [--flag value …]. Command and flag names accept kebab- or snake-case (node set-anchor becomes node.set_anchor). Values that start with [ or { are parsed as JSON. On error the CLI prints the JSON-RPC code, message, and any suggestions to stderr.

The groups#

Discover the catalog#

You don’t have to know a command’s name or flags in advance. The CLI reads the running editor’s catalog and saves project-scoped help for offline use:

swallowtail node --help                            # list a group, one line per command
swallowtail node add --help                        # a param table: flag, type, required, description
swallowtail help all                               # the entire catalog, grouped by category
swallowtail engine commands --group node --docs    # the same, as JSON

Every one of the 337 commands carries param docs, so <group> <command> --help prints a real table rather than a generic hint. engine commands is the JSON form: a flat methods list plus a groups map of group → command names, with --group to narrow and --docs to attach the param docs. Without an editor, help can use this project’s saved catalog and reports its timestamp. An uncached project needs a live editor for addon help. See shell completion and offline help.

Use global --project DIR to select a project from another directory. Use --params-file FILE (or - for stdin) before the group to read a JSON parameter object. Inline parameters override its keys. See Scripting and CI.

How values are coerced#

Godot literals stay strings and are coerced engine-side toward the target type:

swallowtail node set --node-path Player --property position --value "Vector2(100, 200)"
swallowtail node set --node-path Light --property color --value "#ff0000"

• --key value or --key=value for strings, --key=true|false or a bare --flag for booleans.
• JSON arrays and objects when the value starts with [ or {.
• Packed-array properties take a JSON array of the element literal, for example '["Vector2(-64,-64)", "Vector2(64,-64)"]'.
• scene.tree and node.get report node paths relative to the scene root (., UI/Score), so they feed straight back as --node-path. --node-path selected resolves to the editor’s current selection.

Output formats#

On a terminal, a result renders for reading: an object becomes a titled key/value box, an array of objects becomes a table, and values are color-coded by type. Piped or redirected output is exact pretty-printed JSON, so scripts and agents parse the same shape as always without stripping anything. The global --format flag (before the group) pins one of pretty, json, tsv, or ndjson (newline-delimited compact JSON), and the SWALLOWTAIL_FORMAT environment variable does the same for a whole shell when the flag is absent:

swallowtail --format tsv scene tree

TSV renders a success result as tab-separated text for shell pipelines: an array of objects becomes a header row plus one row per element; a single object becomes key/value rows; nested values are emitted as compact JSON, with tabs and newlines escaped. NO_COLOR drops the color from the terminal render without changing its layout.