> 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 on Linux via WINE if you prefer the visual editor. See the [Setup](/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.

## Commands

| Command            | Description                                                                        |
| ------------------ | ---------------------------------------------------------------------------------- |
| `new`              | Create a new Gum project                                                           |
| `check`            | Validate a project for errors                                                      |
| `check-references` | Detect (and optionally fix) `VariableReferences` rows with un-materialized scalars |
| `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                                         |
| `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.gumx --json | jq .
```

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

## Exit Codes

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


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.