agentleFS
vchelaruvchelaru/Gum/.claude/skills/gum-cli/SKILL.md

gum-cli

Skill655 starsChanged 2 months agoMITView on GitHub

GumCli — headless CLI for Gum projects. Triggers: gumcli commands (new, add-forms, check, diff-standards, codegen, codegen-init, fonts, screenshot, svg), Gum.ProjectServices, HeadlessErrorChecker, ProjectLoader, HeadlessCodeGenerationService, CodeGenerationAutoSetupService, FormsTemplateCreator, DiffStandardsService.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Only Screens and Components are generated.

    line 106
  2. Very specific:

    When --element is specified, checkForMissing: true is passed so GenerateCodeForElement auto-generates any referenced elements whose code …

    line 112

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 editor. Primary use cases: CI pipelines, scripting, editor integrations.

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

Commands

CommandPurpose
gumcli new <path> [--template] [--theme <name>] [--platform monogame|kni|kniskia|raylib|stride|silknet] [--source-linked] [--no-restore]Create a new project. Templates: forms (default, includes all Forms UI controls) or empty (minimal). --platform makes <path> a project folder holding a runnable NuGet-referencing host project (PlatformProjectScaffolder; templates embedded under Templates/Platforms/) with the Gum project at Content/GumProject/ and codegen settings written for it, then runs dotnet restore (--no-restore skips). --theme (forms template only) starts from a bundled Forms theme such as Meadow; FormsThemeLocator finds them in the release layout's Content/FormsThemes or in a checkout's Templates/FormsThemes, and FormsTemplateCreator.CreateFromTheme copies one in with its shared behaviors staged into Behaviors/. Standard is the plain template. Tests/Gum.Cli.Tests/ThemeCodegenTests runs new --theme plus codegen over every theme. --source-linked swaps the Gum PackageReference (the {{GumReference}} placeholder in each Host.csproj.template) for a ProjectReference to that platform's runtime csproj in the checkout GumSourceLocator finds by walking up from the gumcli binary, then the cwd. silknet (alias silk.net) scaffolds Gum.SilkNet + Silk.NET.Windowing.Sdl + Silk.NET.Input.Sdl on desktop OpenGL 3.3 core, deliberately without ANGLE so SDL and Skia natives all come from NuGet on Windows/macOS/Linux; kniskia is refused without --source-linked (KniSkiaNeedsSourceLinked; Gum.KniSkia is not on NuGet) and scaffolds Gum.KniSkia + SkiaGameRendering.Kni.DesktopGL, with its own Game1 that draws Gum into a SkiaRenderTarget2D (it shares the XNA Program.cs); fna is rejected (not on NuGet). The valid names live in one table in NewCommand, which the help text and the unknown-platform error both read. The folders and main files a new project gets are one rule set, NewProjectLayout, read by the creators and the New Project dialog; NewProjectLayoutTests pins it against the real creation for every platform, so a folder a template starts writing must be added there. A failed or canceled NewProjectService.CreateFilesAsync deletes only what the run created (NewProjectJournal); a file it overwrote stays as written.
gumcli add-forms <project.gumx|project.gumj>Merge the Forms template's Components/Standards/Behaviors/Fonts/UISpriteSheet.png into an already-existing project, skipping anything already referenced. Refuses (exit 2) when the target project is older than the template, via ImportVersionGate, the same check the tool's imports use. Backed by AddFormsToProjectService, which reuses FormsTemplateCreator against a throwaway temp project rather than duplicating its embedded-resource extraction.
gumcli check <project.gumx> [--json]Validate all elements (.gusx, .gutx, .gucx) that belong to the project. Human-readable or JSON output. Pass the project file, not an element file (an element file exits 2). Use it for post-write validation of the elements you edited.
gumcli check-references <project.gumx> [--json] [--fix]Detect (and optionally fix) VariableReferences rows whose left-hand-side scalars are not materialized into the state's Variables — the inconsistent shape commonly produced by AI agents and hand edits that bypass the Gum tool's author-time propagation. --fix runs ApplyVariableReferences on affected states and saves the modified element files. Scans Screens and Components only (StandardElements have known default-evaluating refs whose missing scalars are correct on-disk state — see gum-tool-variable-references for the model). Exits 1 if anything is unpropagated.
gumcli diff-standards <project.gumx> [--json]Compare the project's Standards against StandardElementsManager.Self's programmatic defaults (the same source the Gum tool's File → New uses) and report variable-level drift. Exits 1 on drift, 0 on clean. Theme authors and CI use it to enforce the "Standards must match Default" invariant.
gumcli convert-to-json <project.gumx>Write a .gumj sibling plus a JSON sibling for every referenced element/behavior/animation file, leaving the XML untouched. Required for Native AOT / PublishTrimmed. Backed by ConvertProjectToJsonService.
gumcli resave <project.gumx> [--raw]Load and save with no edits. Default loads like the tool (runs the standard-element back-fill in GumProjectSave.Initialize); --raw skips it so only the serializers run. Tools/project-sweep.ps1 uses both to sweep real projects.
gumcli codegen <project.gumx> [--element <name>...] [--prune]Generate C# code. Requires ProjectCodeSettings.codsj. Per-element error check gates generation. --prune additionally deletes generated files with no matching element; it only ever removes .Generated.cs, and lists orphaned custom .cs/.codsj files for you to decide on.
gumcli codegen-init <project.gumx> [--force] [--csproj <path>]Auto-detect .csproj, derive namespace and output library, write ProjectCodeSettings.codsj. --csproj also records the path as CsprojPath, which detection then reads ahead of the search. A Unity csproj (Assembly-CSharp.csproj beside Assets/) sets GeneratedCodeFolder = Assets/.
gumcli fonts <project.gumx> [--font <name> --size <n>... [--bold] [--italic] [--outline <n>]]Generate missing bitmap font files (.fnt + .png). --font/--size also bakes fonts no element uses (BBCode runs, oversampled sizes) through ExtraFontRequest; one style per run, invalid combinations exit 2. bmfont.exe is Windows-only; other OSes use KernSmith.
gumcli screenshot <project.gumx> <element> [--output] [--width] [--height] [--backend monogame|raylib] [--background hex]Render a Screen or Component to a PNG via MonoGame DesktopGL (default) or raylib. Pixel-accurate; cross-platform. --background clears to an opaque RRGGBB/RRGGBBAA hex color instead of the default transparent, for a more representative visual comparison. It never generates fonts: a font missing from the project's FontCache/ renders as the default font (logged as "No usable font could be resolved"), so run GumProjectFontGenerator on a scratch copy first when text size matters.
gumcli svg <project.gumx> <element> [--output] [--width] [--height]Render a Screen or Component to a vector SVG via SkiaGum's SKSvgCanvas. Bitmaps embed as base64.
gumcli diff-screenshots <project.gumx>Render every Screen and Component through both MonoGame and raylib and report pixel-level mismatches.
gumcli pack <project.gumx> [--include] [--shake] [--roots <file>] [--keep <names>] [--roots-assembly <dll>] [--skip-debug-only]Pack a project into a .gumpkg bundle. --skip-debug-only (opt-in, independent of --shake) passes the Debug Only elements (DebugOnlyElementLogic, includes derived components) to GumElementReachability.Compute as excluded; without --shake every other element is a root. A kept element that has an instance of or derives from an excluded one exits 2. --shake (opt-in) keeps only the Screens and Components that GumElementReachability (GumCommon/Bundle) reaches from every Screen plus the roots, and drops the files only trimmed elements use; Standards and behaviors are always kept. --roots-assembly reads the [assembly: GumElementRoot] attributes that the GumElementRootGenerator in Tools/Gum.Analyzers writes into a game assembly. A root that names no element exits 2.
gumcli stage-forms-behaviors <project.gumx> <destination>Resolve a Forms theme's behaviors (following shared-file links and overrides) and write them flat into a destination folder.

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

Architecture

Program.cs
  ├── NewCommand      → ProjectCreator / FormsTemplateCreator
  ├── AddFormsCommand → AddFormsToProjectService (loads target, extracts FormsTemplateCreator into a throwaway temp project, merges in anything not already referenced)
  ├── 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

Gum.ProjectServices

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

Key types:

TypeRole
ProjectLoader / IProjectLoaderLoads .gumx; detects malformed XML; returns ProjectLoadResult with fatal errors and non-fatal LoadErrors
NameRulesPure name-validation rules shared by the tool's NameVerifier and the CLI
HeadlessErrorChecker / IHeadlessErrorCheckerValidates base types, behaviors, parent refs, variable types. Delegates from tool's ErrorChecker.
ProjectCreator / IProjectCreatorCreates blank projects with subfolder structure
FormsTemplateCreator / IFormsTemplateCreatorExtracts embedded Forms template resources
AddFormsToProjectService / IAddFormsToProjectServiceMerges Components/Standards/Behaviors/Fonts/UISpriteSheet.png from a FormsTemplateCreator extraction into an already-loaded project, skipping anything already referenced by name
HeadlessCodeGenerationServiceThe single orchestrator for per-element and batch code file generation (GenerateCodeForElements); shared by the CLI and the tool
CodeGenerationAutoSetupServiceWalks up to find .csproj, derives CodeProjectRoot, namespace, output library
CodeOutputProjectSettingsManagerLoads/saves ProjectCodeSettings.codsj
ErrorResultPOCO: ElementName, Message, Severity (Warning/Error), Code (e.g. GUM0006, may be null), FilePath. check --json emits code; scripts should match on it, not message text
DiffStandardsService / IDiffStandardsServiceCompares a loaded project's Standards against StandardElementsManager.Self's programmatic defaults. Returns DiffStandardsResult with Differences, MissingFromProject, ProjectOnlyStandards.
ReferencePropagationService / IReferencePropagationServiceDetects states where a VariableReferences row exists without the corresponding materialized scalars in Variables, and propagates them on demand. Detect returns DetectUnpropagatedReferencesResult. PropagateReferences mutates the project (runs the static ElementSaveExtensions.ApplyVariableReferences per offending state) and returns the modified elements; the caller persists. Walks Screens + Components only; Standards are intentionally skipped (their default-evaluating refs would produce false positives). Expression evaluation depends on whoever wires ElementSaveExtensions.CustomEvaluateExpression — the CLI calls GumExpressionService.Initialize() before invoking.

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

Any command that runs HeadlessErrorChecker must call GumExpressionService.Initialize() first (check and codegen do). GUM0002 evaluates cross-element reference right-hand sides through it and silently reports nothing when it is unwired. Tests that cover this reset ElementSaveExtensions.CustomEvaluateExpression = null first, because other commands in the same test process leave it wired.

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

NameRules holds the name rules that need no tool service (common name check, C# name and keywords, Windows reserved file names, Android file names, Standardize, duplicate behavior names). The tool's NameVerifier delegates to it and keeps only the checks that need tool services; CodegenCommand passes a NameRules straight to CodeGenerationNameVerifier. A new name rule that needs only the name (or a list of existing names) goes in NameRules so the tool and the CLI cannot disagree.

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 does not detect the output library: it leaves OutputLibrary at the GumForms default (Gum Forms, correct for every runtime) and always uses ObjectInstantiationType.FindByName. 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.

The checked-in Templates/FormsTemplate/GumProject.gumx carries BehaviorReference.SourcePath on most shared behaviors (e.g. "../FormsBehaviors/ButtonBehavior.behx"), meant only for Gum.FormsStaging's build-time flattening into the shipped tool's Content/FormsThemes folder. FormsTemplateCreator.Create always extracts every manifest-listed .behx locally into the new project's own Behaviors/ folder, so a SourcePath surviving into the extracted .gumx is stale the moment a real project exists (BehaviorReference.GetRelativeFilePath prefers SourcePath when set, and it never resolves relative to a real project — ToBehaviorSave then silently returns an empty IsSourceFileMissing stub with no error). FormsTemplateCreator.StripStaleBehaviorSourcePaths clears SourcePath on every extracted BehaviorReference right after extraction to prevent this.

A shaken bundle's project file is rewritten. GumProjectSave.Load fails on a reference whose file is missing, so pack --shake saves the project without the trimmed references and lists them in GumProjectSave.TrimmedElements. The runtime reads that list to tell a trimmed element from a misspelled one: ObjectFinder.GetRequiredElementSave (used by generated code from syntax version 7) and the variable-reference error both name --keep. ObjectFinder.GetElementSave still returns null, because Gum probes it internally.

Codegen Flow (non-obvious details)

  • codegen and the tool's Generate All both go through HeadlessCodeGenerationService.GenerateCodeForElements, the one batch orchestrator: it skips NeverGenerate elements, runs an optional gate (the CLI's per-element error check), generates the rest, and writes the fallback file only when Elements is null (whole project). New batch-level steps belong there, not in CodegenCommand or the tool handler. The tool passes its own ElementGenerator (popups, missing-file prompt) and an ICodeFileWriter that retries.
  • Only Screens and Components are generated; StandardElements are intentionally excluded (the per-project StandardElements.Generated.cs fallback registration is the exception: written on a full run, skipped when --element is given)
  • Errors (ErrorSeverity.Error) block generation for that element; warnings print to stderr but do not block
  • A file HeadlessCodeGenerationService can't write (unreachable CodeProjectRoot) is logged, not thrown; codegen gives the service its own ConsoleCodeGenLogger and exits 1 when that logger's ErrorCount is non-zero
  • codegen warns on stderr (never blocks) when the csproj's PackageReference runtime version is newer than the CLI's own version: StaleCliWarning.GetMessage compares them, SyntaxVersionDetectionService.FindRuntimePackageVersion reads the package version. ProjectReference, HintPath, and unresolvable floating or range versions stay silent.
  • 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. A .codsj that exists but cannot be parsed (including an empty file) is reported with the parser message, left untouched, and exits 2; it is never replaced by auto-detected defaults. A readable .codsj with a blank CodeProjectRoot gets only that key filled in and written back (other keys, unknown ones included, are kept)
  • 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

FilePurpose
Tools/Gum.Cli/Program.csEntry point, assembles RootCommand
Tools/Gum.Cli/Commands/One file per command
Gum.ProjectServices/ProjectLoader.csHeadless project loading
Gum.ProjectServices/HeadlessErrorChecker.csAll headless error checks
Gum.ProjectServices/CodeGeneration/HeadlessCodeGenerationService.csHeadless codegen orchestration
Gum.ProjectServices/CodeGeneration/CodeGenerator.csMain codegen engine (~5400 lines)
Tests/Gum.Cli.Tests/CLI command tests
Tests/Gum.ProjectServices.Tests/Service layer tests (36 tests)

Testing Notes

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.