Skip to content

🫧 Gum β€” Terminal UI EnhancementΒΆ

charmbracelet/gum is an optional dependency that provides beautifully styled terminal output (borders, spinners, styled text, selection menus) when installed. All output gracefully falls back to standard Zsh print -P with ANSI codes when gum is not available.

πŸ“¦ InstallationΒΆ

# mise (recommended)
mise use -g gum

# Arch / Manjaro
sudo pacman -S gum

# Homebrew (macOS / Linux)
brew install gum

# apt (Debian / Ubuntu)
sudo apt install gum

Verify: command -v gum && gum --version

πŸ—οΈ ArchitectureΒΆ

The ZSHAND framework has two separate gum integration layers:

Layer File Language Scope
Runtime IO shared_functions/00_gum_io.zsh Zsh All framework output (core, hooks, startup, functions, widgets, build)
Installers installers/general/gum_helpers.sh Bash Installer scripts only (POSIX-ish, standalone)

The runtime layer is the primary integration point. It provides:

  • Cached gum detection β€” _ZSHAND_HAS_GUM integer flag, set once at source time
  • Zero-cost checks β€” (( _ZSHAND_HAS_GUM )) is a single integer comparison
  • Terminal detection β€” Gum is bypassed when stdout/stderr is not a TTY
  • Safe mode bypass β€” ZSHAND_SAFE_MODE=1 forces all output to plain text

🎨 Function Reference¢

Core Log FunctionsΒΆ

These replace the original 01_stderr_error.zsh, 02_stderr_warn.zsh, 04_echo_info.zsh, and 05_echo_ok.zsh (which are now backward-compat stubs).

Function Channel Gum Mode Fallback
stderr_error "msg" stderr gum log --level error print -P "%F{red}󱈸 ERROR:%f msg"
stderr_warn "msg" stderr gum log --level warn print -P "%F{yellow}󱈸 Warning:%f msg"
echo_info "msg" stdout gum log --level info print -P "%F{blue}πŸ“ msg%f"
echo_ok "msg" stdout gum log --prefix βœ“ print -P "%F{green}βœ“ msg%f"

Rich Output FunctionsΒΆ

Function Purpose Gum Mode Fallback
az_banner "text" Double-border title banner gum style --border double ASCII ══ box
az_header "text" Bold section header gum style --bold ── text ──
az_note "text" [color] Callout box gum style --border rounded ASCII β”Œβ”€β” box
az_divider Horizontal line gum style --foreground 240 ────────
az_step N M "label" Step counter [N/M] gum style --bold Plain [N/M] label
az_done "text" Green completion banner gum style --border rounded βœ“ text
az_progress "icon" "color" "msg" Progress indicator gum style --foreground print -P "%F{color}..."
az_styled_box "color" ["content"] Colored border box (pipe or string) gum style --border rounded ASCII ━━━ box

Interactive FunctionsΒΆ

Function Purpose Gum Mode Fallback
az_spin "title" cmd... Spinner with βœ“/βœ— result gum spin --title echo -n "title ... "; cmd
az_confirm "prompt" [opts] Y/N confirmation gum confirm echo -n "prompt (Y/n) "; read
az_choose "A" "B" "C" Single selection menu gum choose Numbered list + read
echo ... \| az_filter_multi Multi-select with search gum filter --no-limit cat (passthrough)
az_input "prompt" "default" Text input gum input echo -n "prompt [default]: "; read

Timer FunctionsΒΆ

Function Purpose
az_timer_start Record start time
az_elapsed Print "completed in Nm Ns"

βš™οΈ Environment VariablesΒΆ

Variable Type Default Description
_ZSHAND_HAS_GUM int auto 1 if gum found, 0 otherwise. Set at source time.
ZSHAND_SAFE_MODE bool 0 Forces gum off when 1
GUM_SPIN_SPINNER string dot Gum spinner style
GUM_SPIN_SPINNER_FOREGROUND string 212 Spinner color
GUM_CONFIRM_PROMPT_FOREGROUND string 212 Confirm prompt color

πŸ§ͺ TestingΒΆ

# Run the gum IO spec
just test spec/shared_functions/gum_io_spec.sh

# Run all shared function specs
just test spec/shared_functions/

Tests force fallback mode by setting _ZSHAND_HAS_GUM=0 after sourcing, ensuring all fallback code paths are exercised regardless of whether gum is installed on the test machine.

Document Purpose
shared_functions/00_gum_io.zsh Implementation
SHARED_FUNCTIONS.md All shared function docs
STYLE_GUIDE.md IO pattern conventions
plans/refactor-io-to-gum.md Migration plan
installers/general/gum_helpers.sh Bash installer layer