# Gumcli

> gumcli

- Skill: `vchelaru/gumcli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vchelaru/gumcli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vchelaru/gumcli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vchelaru (https://skillmd.com/u/vchelaru)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vchelaru/gumcli

---


# gumcli

`gumcli` is a cross-platform .NET tool for working with Gum projects **without**
the editor. It is the primary way an AI assistant acts on a Gum project and
verifies its own work: machine-readable output on stdout, meaningful exit codes,
fully headless. Full reference: <https://docs.flatredball.com/gum/cli>.

## Install

```
dotnet tool install -g GumCli
```

## The edit → validate → verify loop

After **any** change to a Gum project (by hand, by tool, or by an assistant),
run this loop. Skipping validation is the most common way agent-authored UI
breaks silently.

### 1. Generate code (project + codegen mode only)

```
gumcli codegen-init  MyProject.gumx     # once: writes code-gen settings
gumcli codegen       MyProject.gumx     # after any element edit: emits typed C#
```

Regenerate after editing elements so the generated classes match the XML. If you
rename or delete an element, delete its stale generated `.cs` file before
regenerating.

### 2. Validate — always

```
gumcli check MyProject.gumx            # human-readable
gumcli check MyProject.gumx --json     # machine-readable
```

`check` catches the mistakes that are easy to make and invisible otherwise —
most importantly **misspelled XML element names that Gum drops without error**
(see **gum-file-format**). Exit code `0` = clean, `1` = errors found, `2` =
project could not be loaded / bad arguments. Branch on the exit code; do not
parse prose. Run `check` after every hand edit before trusting the file.

### 3. Verify visually

Compiling is not proof the UI looks right. Render it and inspect:

```
gumcli screenshot MyProject.gumx ScreenOrComponentName --output out.png
gumcli svg        MyProject.gumx ScreenOrComponentName --output out.svg
```

Open the image to confirm layout matches intent. With a multimodal model, the
assistant can look at the PNG directly.

## Other commands

| Command | Purpose |
|---------|---------|
| `gumcli new <path> [--template forms\|empty]` | Scaffold a new project. `forms` (default) includes the built-in Forms controls. |
| `gumcli fonts <project.gumx>` | Generate missing bitmap font files (`.fnt`+`.png`). **Windows-only.** |
| `gumcli pack <project.gumx>` | Bundle a project into a single file. |

## Notes

- **stdout is data, stderr is chatter.** Consume results (`--json`, paths) from
  stdout; banners and progress go to stderr.
- Pair `gumcli` with the MCP documentation server so the assistant can look up a
  property while it drives the project. See
  <https://docs.flatredball.com/gum/ai/gumcli-for-agents>.