Commands
Every gdsuite command, its options, and how to pass options to the tool behind it.
Commands
| Command | What it does |
|---|---|
gdsuite init | Optional: write a gdsuite.toml with every setting at its default, and install the test addons |
gdsuite setup | Install the tools [tools] asks for, and repair the test addons |
gdsuite update | Bring a project set up by GDSuite 0.4 or earlier up to date: removes old tool versions from [tools] and the downloaded tools from .gdsuite/ |
gdsuite migrate | Move older settings (gdtest.toml, gdhealth.toml, gdtidy.toml, gdlintrc, gdformatrc, settings from GDSuite 0.1) into gdsuite.toml |
gdsuite doctor | Show where Godot and each tool are, their versions, and what is missing |
gdsuite fmt | Format the project's scripts |
gdsuite lint | Lint the project's scripts |
gdsuite typecheck | Type check the project |
gdsuite test | Run the tests in default_test_target (test/) |
gdsuite health | Measure code health |
gdsuite check | Run the check steps in order, stopping at the first that fails |
gdsuite report [NAME] | Print a saved report: latest (the default), check, test, health, or ci to combine them |
gdsuite config get|set|unset|add|remove KEY [VALUE] | Read or change gdsuite.toml, keeping its comments. Keys are dotted (lint.disable, editor.format_on_save); a change gdsuite can't read is undone |
Options
Every command takes:
| Option | Default | Description |
|---|---|---|
--project-root <DIR> | . | The Godot project |
--godot-exe <PATH> | Remembered by init, then GODOT_EXE, then found automatically | The Godot 4 program |
Some also take:
| Option | Commands | Description |
|---|---|---|
--output pretty|plain|json | init, setup, update, doctor | pretty for people (the default), plain for stable lines in scripts and CI logs, json for programs |
--report text|json | lint, typecheck, test, health, check | Print the result as text or JSON. lint and typecheck give the same JSON shape; test, health and check also save it in reports/gdsuite/ |
--input <FILE> | fmt | Print the file's text formatted with the project's settings, and change no file. For editors, to format unsaved text |
Passing options to a tool
Each feature is run by a tool that GDSuite installs (see Under the
hood). Everything after -- goes to that tool unchanged:
gdsuite fmt -- --check # change nothing, list what would change
gdsuite lint -- --fix player/ # fix what can be fixed, in player/
gdsuite typecheck -- --strict # also check calls on your own classes
gdsuite test -- --filter combat # only tests whose name matches
gdsuite health -- health --fail-on criticalFor gdsuite health, what follows -- replaces the default health
subcommand, so start with it.
The options of each tool:
- formatting and linting: Formatting style and gdtidy's command reference
- type checking: gdtypecheck's command reference
- tests: Filters, tags and coverage and gdtest's command reference
- code health: gdhealth's command reference
Exit codes
0 means everything passed. Anything else means a check found a problem or
could not run; the last lines of the output say which.