> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/cli/cli.md).

# GumCli

**GumCli** (`gumcli`) is a cross-platform command-line tool for working with Gum UI projects. It lets you create projects, check for errors, and generate C# code without opening the **Gum** editor.

## When to Use GumCli

Use **GumCli** when:

* You want to edit Gum project XML files by hand or with your own tooling, and need to validate or generate code without launching the editor
* You want to integrate code generation into a build pipeline (CI/CD) without committing generated code to source control
* You are building a custom tool or automation that works with Gum projects
* You are an AI agent working with Gum projects programmatically

{% hint style="info" %}
The full **Gum** tool runs natively on Windows, macOS, and Linux if you prefer the visual editor. See the [Setup](https://docs.flatredball.com/gum/gum-tool/setup.md) page for details.
{% endhint %}

## Installation

Install **GumCli** as a .NET global tool:

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

Once installed, invoke it as `gumcli` from any terminal.

To install a preview version, which includes changes that have not reached a stable release yet, add `--prerelease`:

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

## Version

```
gumcli --version
```

Every command also prints `gumcli v<version>` to stderr, so the version appears at the top of any run's output. Compare it to the latest on [NuGet](https://www.nuget.org/packages/GumCli).

## Updating

`gumcli` is not updated when you update the Gum NuGet packages in your game. Update it separately:

```
dotnet tool update -g GumCli
```

To update to the latest preview version, add `--prerelease`:

```
dotnet tool update -g GumCli --prerelease
```

Update whenever you update the Gum runtime packages. Generated code can target APIs a stale `gumcli` doesn't know about.

If you run a preview version of the **Gum** tool, use the `gumcli` that matches it. Each **Gum** tool release includes a `GumCli` folder built from the same commit, so its output matches the tool.

## Commands

| Command                 | Description                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `new`                   | Create a new Gum project                                                           |
| `add-forms`             | Add the Forms controls to an existing project                                      |
| `check`                 | Validate a project for errors                                                      |
| `check-references`      | Detect (and optionally fix) `VariableReferences` rows with un-materialized scalars |
| `convert-to-json`       | Write a JSON copy of an XML project and its element files                          |
| `diff-standards`        | Report how a project's Standard elements differ from the defaults                  |
| `import-screen`         | Import a Screen file into an existing project                                      |
| `resave`                | Load and save a project with no edits to check round trips                         |
| `edit`                  | Apply a list of changes from a JSON file to a project                              |
| `describe`              | List the variables an element or instance can set, and its states and categories   |
| `stage-forms-behaviors` | Write a Forms theme's resolved behaviors into one folder                           |
| `codegen-init`          | Initialize code generation settings                                                |
| `codegen`               | Generate C# code for project elements                                              |
| `fonts`                 | Generate missing bitmap font files                                                 |
| `pack`                  | Pack a project into a single `.gumpkg` bundle                                      |
| `screenshot`            | Render a Screen or Component to a PNG file                                         |
| `diff-screenshots`      | Render every Screen and Component via MonoGame and raylib and report mismatches    |
| `svg`                   | Render a Screen or Component to an SVG file                                        |

## Output Streams

`gumcli` writes machine-readable command output (JSON, file paths, summaries) to **stdout**, and informational chrome (the version banner, progress messages, error details) to **stderr**. This split means automation can consume stdout directly without filtering:

```
gumcli check MyProject/MyProject.gumj --json | jq .
```

When debugging, capture both streams with `2>&1`.

## Exit Codes

| Code | Meaning                                                                                                                                                     |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | Success                                                                                                                                                     |
| 1    | Errors found (`check`), an edit that could not apply or added errors (`edit`), or elements blocked by errors (`codegen`) or font generation error (`fonts`) |
| 2    | Project could not be loaded, invalid arguments, or settings already exist                                                                                   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flatredball.com/gum/cli/cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
