By name: gum
description: Reference for using the gum CLI tool from Charmbracelet to create glamorous shell scripts with interactive TUI components. Use when building interactive prompts, styling terminal output, displaying spinners, or creating user-facing CLI experiences. CRITICAL - many gum commands are interactive TUIs that block waiting for user input.
Gum CLI Reference
Gum is a tool for glamorous shell scripts, providing interactive TUI components and text styling.
When to Use
- Building interactive shell prompts (choose, confirm, input, filter)
- Styling terminal output with colors, borders, and formatting
- Creating user-facing CLI experiences with spinners or progress indicators
- Writing scripts that need structured text display (tables, logs, joined blocks)
Critical: Interactive vs Non-Interactive Commands
INTERACTIVE (block for user input - cannot be used directly by Claude):
choose- select from listconfirm- yes/no promptfile- file pickerfilter- fuzzy filter listinput- single-line text inputpager- scroll through contenttable- interactive table selectionwrite- multi-line text input
NON-INTERACTIVE (safe for Claude to use directly):
style- apply colors/borders to textformat- format markdown/code/emojijoin- combine text blockslog- structured logging outputspin- show spinner while running a command (runs the command, not interactive)
Command Summary
| Command | Purpose | Key Flag |
|---|---|---|
choose |
Select from options | --header, --limit, --height |
confirm |
Yes/no prompt | --affirmative, --negative |
input |
Single-line text input | --placeholder, --password |
write |
Multi-line text input | --header, --show-line-numbers |
filter |
Fuzzy filter list | --strict, --no-fuzzy |
file |
File picker (buggy — prefer fzf) |
--all, --directory |
table |
Interactive table | --print (non-interactive mode) |
spin |
Spinner while running command | --show-output, --spinner |
style |
Apply colors/borders to text | --border, --foreground |
format |
Format markdown/code/emoji | --type, --language |
join |
Combine text blocks | --horizontal, --vertical |
log |
Structured logging output | --level, --structured |
pager |
Scroll through content | --show-line-numbers |
Consult references/commands.md for full flag reference and examples for each command.
Styling Colors
Colors can be specified as:
| Format | Example |
|---|---|
| ANSI codes | 212, 0, 255 |
| Hex | "#FF0000", "#0FF" |
| Named | "red", "blue" (some terminals) |
Common ANSI codes:
| Code | Color |
|---|---|
212 |
pink/magenta |
99 |
purple |
10 |
green |
9 |
red |
11 |
yellow |
240 |
gray |
Environment Variables
All flags can be set via environment variables:
- Pattern:
GUM_<COMMAND>_<FLAG> - Examples:
GUM_INPUT_PLACEHOLDER="Enter value",GUM_CHOOSE_HEIGHT=15,GUM_SPIN_SPINNER=dot
Exit Codes
| Command | Code | Meaning |
|---|---|---|
gum confirm |
0 | Yes |
gum confirm |
1 | No |
gum filter --strict |
1 | No match found |
| Other commands | 0 | Success |
| Other commands | non-zero | Error or cancel |
Dependencies
- gum —
brew install gum(charmbracelet/gum)
Reference Files
| File | Contents |
|---|---|
references/commands.md |
Complete command reference with all flags and examples |
references/patterns.md |
Common multi-command patterns (commit messages, wizards, dashboards) |