Gum CLI

GumCli Reference

What It Is

GumCli (gumcli) is a cross-platform .NET 8.0 console app that lets developers create, validate, and generate code for Gum projects without the WPF editor. Primary use cases: CI pipelines, scripting, editor integrations.

Location: Tools/Gum.Cli/ Depends on: Gum.ProjectServices → GumCommon

Commands

Exit codes: 0 = success, 1 = errors found / generation blocked, 2 = load failure, bad args, or non-Windows (fonts).

Architecture

Program.cs
  ├── NewCommand      → ProjectCreator / FormsTemplateCreator
  ├── CheckCommand    → ProjectLoader → HeadlessErrorChecker
  ├── CheckReferencesCommand → ProjectLoader → ReferencePropagationService (Detect / PropagateReferences). Wires GumExpressionService so literal/expression RHSes evaluate; sets ObjectFinder.Self.GumProjectSave so cross-element refs resolve.
  ├── DiffStandardsCommand → ProjectLoader → DiffStandardsService (project Standards vs StandardElementsManager.Self defaults)
  ├── CodegenCommand  → ProjectLoader → HeadlessErrorChecker (gates) → HeadlessCodeGenerationService
  ├── CodegenInitCommand → CodeGenerationAutoSetupService
  ├── FontsCommand    → ProjectLoader → HeadlessFontGenerationService (Windows-gated)
  ├── ScreenshotCommand → MonoGameScreenshotService (Gum.ProjectServices.MonoGame)
  └── SvgCommand      → SkiaGumSvgExportService (Gum.ProjectServices.SkiaGum)

Each command class has a static Create() returning a System.CommandLine Command with handler, then a static Execute() doing the work.

CLI-specific adapters:

• ConsoleCodeGenLogger — implements ICodeGenLogger, writes to stdout/stderr
• HeadlessNameVerifier — implements INameVerifier for C# name validation

Gum.ProjectServices

The headless service library GumCli depends on. All logic lives here; the CLI just wires it together.

Key types:

Non-obvious: HeadlessErrorChecker is not a duplicate of the tool's ErrorChecker — the tool's ErrorChecker delegates to HeadlessErrorChecker. Zero duplication by design.

HeadlessErrorChecker accepts a second constructor overload taking IEnumerable<IAdditionalErrorSource> for extensibility; the CLI uses the single-argument overload.

HeadlessNameVerifier only implements real logic in IsValidCSharpName; all other INameVerifier methods return true unconditionally. This is intentional — the CLI only needs C# name validation for codegen.

ProjectLoader runs DetectSilentlyDroppedContent after deserialization to catch incorrect XML element names (e.g., <States> instead of <State>, <InstanceSave> instead of <Instance>) that XmlSerializer silently ignores. Without this, AI-generated files with wrong structure load as empty elements with no error.

CodeGenerationAutoSetupService detects MonoGame vs non-MonoGame projects by scanning for <PackageReference Include="MonoGame.Framework. or nkast.Xna.Framework in the .csproj, then sets OutputLibrary accordingly (to MonoGameForms, not plain MonoGame). It also detects <PackageReference Include="Raylib-cs" and sets OutputLibrary.Raylib — there is no "RaylibForms" auto-detect target since Raylib codegen only supports ObjectInstantiationType.FindByName so far (see gum-tool-codegen). Namespace falls back to the .csproj filename (dots/dashes/spaces replaced with underscores) when <RootNamespace> is absent.

codegen fails fast with exit code 1 if the resolved settings request an unsupported combination (currently: OutputLibrary.Raylib + ObjectInstantiationType.FullyInCode) — CodeGenerator.AssertSupportedCombination throws NotSupportedException, and CodegenCommand catches it before touching the file system.

CodeGenerationAutoSetupService has two Run overloads: Run(gumxFilePath) for auto-detection, and Run(gumxFilePath, explicitCsprojPath) for when the caller already knows the .csproj path. The explicit overload validates the file exists and skips directory walking entirely; all namespace/OutputLibrary derivation logic is shared via the private BuildResultFromCsprojDirectory helper.

DiffStandardsService compares the loaded project against a fresh reference built by StandardElementsManager.Self.PopulateProjectWithDefaultStandards(...) — the same path the tool's File → New uses. The CLI matches the tool's import-dialog drift detection by construction. gumcli new --template empty's Standards/*.gutx files are generated from that same call at creation time (#4676) rather than extracted from a baked resource, so a fresh empty project is drift-free by construction, not by convention.

Font files are named like Font18Arial.fnt and Font18Arial_0.png (size+name convention, zero-indexed). Always use gumcli fonts <project.gumx> to generate missing bitmap fonts — never create .fnt files manually.

Codegen Flow (non-obvious details)

• codegen iterates elements individually (not via GenerateCodeForAllElements) so it can run per-element error checks first; GenerateCodeForAllElements exists on HeadlessCodeGenerationService but the CLI does not call it
• Only Screens and Components are generated; StandardElements are intentionally excluded
• Errors (ErrorSeverity.Error) block generation for that element; warnings print to stderr but do not block
• ObjectFinder.Self cache is managed at the CLI level (enabled before the loop, disabled in finally)
• If ProjectCodeSettings.codsj is missing, codegen attempts CodeGenerationAutoSetupService auto-detection first and writes the settings file before continuing; exit code 2 only if auto-detection also fails
• When --element is specified, checkForMissing: true is passed so GenerateCodeForElement auto-generates any referenced elements whose code files do not yet exist; full-run mode skips that check
• codegen-init exits with code 2 (not 1) if settings already exist and --force is absent

Key Files

Testing Notes

• ObjectFinder is a singleton — tests disable parallel execution (TestAssemblyInitialize)
• BaseTestClass pre-populates GumProjectSave with standard elements and handles ObjectFinder.Self cleanup