# Gum — A Tool for Glamorous Shell Scripts by Charm

> Gum is a CLI toolkit for building interactive shell scripts with spinners, prompts, file pickers, tables, and styled output — turning bash scripts into modern TUI experiences.

## Install

Save in your project root:

# Gum — A Tool for Glamorous Shell Scripts by Charm

## Quick Use
```bash
brew install gum
# Interactive commit message
TYPE=$(gum choose feat fix docs style refactor test chore)
SCOPE=$(gum input --placeholder "scope")
MSG=$(gum input --placeholder "summary")
git commit -m "$TYPE($SCOPE): $MSG"
# Spinner while long command runs
gum spin --spinner dot --title "Deploying..." -- ./deploy.sh
```

## Introduction
Gum is part of the Charm toolkit (bubbletea, lipgloss). It exposes every TUI building block as a standalone subcommand you can call from bash, making your install scripts, setup wizards, and dev-ops runbooks actually pleasant to use. It's the missing UI layer between bash and full Go TUI apps.

## What Gum Does
- `gum input` — prompt with placeholders, masks, validation.
- `gum choose` — single/multi-select from a list.
- `gum confirm` — yes/no dialog with keyboard controls.
- `gum file` — file picker TUI.
- `gum spin` — spinner around any subprocess.
- `gum style` / `gum format` — paint text with lipgloss.
- `gum table` — render CSVs as styled tables.
- `gum log` — leveled structured log output.

## Architecture Overview
Each subcommand is a thin CLI over a bubbletea program. The output goes to stdout (as the selected value) while the TUI draws on stderr, so composing with `$(gum ...)` in bash just works. `--theme` / lipgloss flags customize colors without any global config.

## Self-Hosting & Configuration
- Install via brew, apt, dnf, pacman, scoop, winget.
- Themes via flags: `--height`, `--cursor`, `--prompt`, `--cursor.foreground`.
- `GUM_*` env vars mirror flags.
- Works in CI when `--no-color` or `CI=true`.
- Pair with `charm freeze` to render docs.

## Key Features
- Composes with bash — drop into existing scripts.
- Every TUI primitive (input, choose, file, spin, table).
- Beautiful defaults; deeply themeable.
- Small static Go binary; cross-platform.
- CI-friendly degradation.

## Comparison with Similar Tools
- **fzf** — unmatched for fuzzy-select; gum's `choose` is simpler + themed.
- **dialog/whiptail** — retro, curses-based; gum is modern.
- **bubbletea (Go lib)** — for full apps; gum is for scripts.
- **inquirer.js** — Node-only.
- **enquirer** — Node-only.

## FAQ
**Q: Read password without echo?**
A: `gum input --password`.

**Q: Multi-select?**
A: `gum choose --no-limit`.

**Q: Works over SSH?**
A: Yes, as long as the TTY is present.

**Q: Reusable themes?**
A: Export `GUM_INPUT_CURSOR_FOREGROUND=212` etc. in a sourcing script.

## Sources
- https://github.com/charmbracelet/gum
- https://charm.sh

---
Source: https://tokrepo.com/en/workflows/43c00283-38c4-11f1-9bc6-00163e2b0d79
Author: AI Open Source