GDSuite Docs

Commands

Every gdsuite command, its options, and how to pass options to the tool behind it.

Commands

CommandWhat it does
gdsuite initOptional: write a gdsuite.toml with every setting at its default, and install the test addons
gdsuite setupInstall the tools [tools] asks for, and repair the test addons
gdsuite updateBring 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 migrateMove older settings (gdtest.toml, gdhealth.toml, gdtidy.toml, gdlintrc, gdformatrc, settings from GDSuite 0.1) into gdsuite.toml
gdsuite doctorShow where Godot and each tool are, their versions, and what is missing
gdsuite fmtFormat the project's scripts
gdsuite lintLint the project's scripts
gdsuite typecheckType check the project
gdsuite testRun the tests in default_test_target (test/)
gdsuite healthMeasure code health
gdsuite checkRun 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:

OptionDefaultDescription
--project-root <DIR>.The Godot project
--godot-exe <PATH>Remembered by init, then GODOT_EXE, then found automaticallyThe Godot 4 program

Some also take:

OptionCommandsDescription
--output pretty|plain|jsoninit, setup, update, doctorpretty for people (the default), plain for stable lines in scripts and CI logs, json for programs
--report text|jsonlint, typecheck, test, health, checkPrint 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>fmtPrint 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 critical

For gdsuite health, what follows -- replaces the default health subcommand, so start with it.

The options of each tool:

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.