Building Glamorous TUIs with Charmbracelet

Quick Router

What are you building?

For Shell Scripts

No Go required. Gum gives you all the UI primitives.

brew install gum

Essential Gum Commands

# Input
NAME=$(gum input --placeholder "Your name")

# Selection (single)
COLOR=$(gum choose "red" "green" "blue")

# Selection (multi)
ITEMS=$(gum choose --no-limit "a" "b" "c")

# Fuzzy filter (from stdin)
BRANCH=$(git branch | gum filter)

# Confirmation
gum confirm "Continue?" && echo "yes"

# Spinner
gum spin --title "Working..." -- long-command

# Styled output
gum style --border rounded --padding "1 2" "Hello"

# File picker
FILE=$(gum file .)

Quick Recipe: Git Commit

TYPE=$(gum choose "feat" "fix" "docs" "refactor")
MSG=$(gum input --placeholder "commit message")
gum confirm "Commit?" && git commit -m "$TYPE: $MSG"

VHS Quick Start

Record terminal → GIF:

brew install vhs

cat > demo.tape << 'EOF'
Output demo.gif
Set Theme "Catppuccin Mocha"
Type "echo hello"
Enter
Sleep 1s
EOF

vhs demo.tape

Other Shell Tools

Full Shell Reference →

For Go Applications

Instant Start

go get github.com/charmbracelet/bubbletea \
       github.com/charmbracelet/lipgloss

Minimal TUI (Copy & Run)

package main

import (
    "fmt"
    tea "github.com/charmbracelet/bubbletea"
    "github.com/charmbracelet/lipgloss"
)

var highlight = lipgloss.NewStyle().Foreground(lipgloss.Color("212")).Bold(true)

type model struct {
    items  []string
    cursor int
}

func (m model) Init() tea.Cmd { return nil }

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        switch msg.String() {
        case "q", "ctrl+c":
            return m, tea.Quit
        case "up", "k":
            if m.cursor > 0 { m.cursor-- }
        case "down", "j":
            if m.cursor < len(m.items)-1 { m.cursor++ }
        case "enter":
            fmt.Printf("Selected: %s\n", m.items[m.cursor])
            return m, tea.Quit
        }
    }
    return m, nil
}

func (m model) View() string {
    s := ""
    for i, item := range m.items {
        if i == m.cursor {
            s += highlight.Render("▸ "+item) + "\n"
        } else {
            s += "  " + item + "\n"
        }
    }
    return s + "\n(↑/↓ move, enter select, q quit)"
}

func main() {
    m := model{items: []string{"Option A", "Option B", "Option C"}}
    tea.NewProgram(m).Run()
}

Library Cheat Sheet

Quick Patterns

Styled Output (no TUI):

style := lipgloss.NewStyle().Foreground(lipgloss.Color("205")).Bold(true)
fmt.Println(style.Render("Hello!"))

Simple Form (no TUI):

var name string
huh.NewInput().Title("Your name?").Value(&name).Run()

Confirmation:

var ok bool
huh.NewConfirm().Title("Delete?").Value(&ok).Run()

Full Go TUI Reference → Component API → Advanced Patterns →

For Infrastructure

Wish: SSH Apps

Serve TUI over SSH:

s, _ := wish.NewServer(
    wish.WithAddress(":2222"),
    wish.WithHostKeyPath(".ssh/key"),
    wish.WithMiddleware(
        bubbletea.Middleware(handler),
        logging.Middleware(),
    ),
)
s.ListenAndServe()

Connect: ssh localhost -p 2222

Other Infrastructure

Testing TUIs

tm := teatest.NewTestModel(t, model)
tm.Send(tea.KeyMsg{Type: tea.KeyEnter})
tm.Type("hello")
teatest.WaitFor(t, tm, func(b []byte) bool {
    return strings.Contains(string(b), "expected")
})

Full Infrastructure Reference →

Decision Guide

Is it a shell script?
├─ Yes → Use Gum
│        Need recording? → VHS
│        Need AI? → Mods
│
└─ No (Go application)
   │
   ├─ Just need styled output?
   │  └─ Lip Gloss only (no Bubble Tea)
   │
   ├─ Need simple prompts/forms?
   │  └─ Huh standalone
   │
   ├─ Need full interactive TUI?
   │  └─ Bubble Tea + Bubbles + Lip Gloss
   │
   └─ Need SSH access?
      └─ Wish + Bubble Tea

When NOT to Use Charm

• Output is piped: mytool | grep → plain text
• CI/CD: No terminal → use flags/env vars
• One simple prompt: Maybe fmt.Scanf is fine

Escape hatch:

if !term.IsTerminal(os.Stdin.Fd()) || os.Getenv("NO_TUI") != "" {
    runPlainMode()
    return
}

All References