check-references
gumcli check-references <project.gumj> [--json] [--fix]Detects (and optionally fixes) VariableReferences rows whose left-hand-side scalars are not materialized into the owning state's Variables. This inconsistent shape is most commonly produced by AI agents and hand edits that write the references row without running the propagation Gum normally performs when references are authored interactively.
When the Gum tool resolves a reference at author time, it writes the evaluated right-hand-side as a hard scalar into the same state's Variables. The references row and the materialized scalar are both persisted to disk. Files that have the row but not the scalar read as fallthrough-to-default at runtime — even though the Variables tab in the editor will appear to show the correct value once the file is opened and re-saved.
Use this command from AI agents and CI pre-commit hooks to detect (and optionally repair) these inconsistencies before they reach disk.
Options
<project.gumj>— Path to the.gumjor.gumxproject file--json— Output results as JSON instead of human-readable text--fix— Propagate references on affected states and save the modified element files
Examples
gumcli check-references MyProject/MyProject.gumj
gumcli check-references MyProject/MyProject.gumj --json
gumcli check-references MyProject/MyProject.gumj --fixWhat it scans
Screens and Components only. StandardElements are intentionally skipped — the system-generated standards contain references whose evaluated values equal the type default (e.g. Text.Tiny → IsBold = Styles.Tiny.IsBold resolves to false), and Gum's save pipeline correctly elides default-valued scalars. Treating those as failures would produce noisy false positives.
Output
No issues (human-readable):
Issues found (human-readable):
Each line follows the format: <element> [<state>]: <message>.
JSON output:
With --fix:
If a right-hand side cannot be evaluated (e.g. references a missing element), the corresponding state remains broken and is listed under "The following references could not be evaluated".
Exit Codes
0
No unpropagated references (or all were fixed)
1
One or more elements still have unpropagated references
2
Project file could not be loaded
Last updated
Was this helpful?

