building-glamorous-tuis

What are you building?

| Context | Solution | Reference |

|---------|----------|-----------|

| Shell/Bash script | Gum, VHS, Mods, Freeze | [→ Shell Scripts](#for-shell-scripts) |

| Go CLI/TUI | Bubble Tea + Lip Gloss | [→ Go TUI](#for-go-applications) |

| SSH-accessible app | Wish + Bubble Tea | [→ Infrastructure](#for-infrastructure) |

| Recording demos | VHS | [→ Shell Scripts](#vhs-quick-start) |

| Testing TUIs | teatest | [→ Infrastructure](#for-infrastructure) |

---

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

```bash

brew install gum

```

Essential Gum Commands

```bash

# 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

```bash

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:

```bash

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

| Tool | Install | One-liner |

|------|---------|-----------|

| Mods | brew install mods | git diff \| mods "review this" |

| Glow | brew install glow | glow README.md |

| Freeze | brew install freeze | freeze code.go -o screenshot.png |

[Full Shell Reference →](references/shell-scripts.md)

---

Instant Start

```bash

go get github.com/charmbracelet/bubbletea \

github.com/charmbracelet/lipgloss

```

Minimal TUI (Copy & Run)

```go

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

| Need | Library | Example |

|------|---------|---------|

| TUI framework | bubbletea | tea.NewProgram(model).Run() |

| Components | bubbles | list.New(), textinput.New() |

| Styling | lipgloss | style.Foreground(lipgloss.Color("212")) |

| Forms (simple) | huh | huh.NewInput().Title("Name").Run() |

| Markdown | glamour | glamour.Render(md, "dark") |

| Animation | harmonica | harmonica.NewSpring() |

Quick Patterns

Styled Output (no TUI):

```go

style := lipgloss.NewStyle().Foreground(lipgloss.Color("205")).Bold(true)

fmt.Println(style.Render("Hello!"))

```

Simple Form (no TUI):

```go

var name string

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

```

Confirmation:

```go

var ok bool

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

```

[Full Go TUI Reference →](references/go-tui.md)

[Component API →](references/component-catalog.md)

[Advanced Patterns →](references/advanced-patterns.md)

---

Wish: SSH Apps

Serve TUI over SSH:

```go

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

| Tool | Purpose | Install |

|------|---------|---------|

| Soft Serve | Self-hosted Git | brew install soft-serve |

| Pop | Send email | brew install pop |

| Skate | Key-value store | brew install skate |

| Melt | SSH key backup | brew install melt |

| Wishlist | SSH gateway | go install github.com/charmbracelet/wishlist |

Testing TUIs

```go

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 →](references/infrastructure.md)

---

```

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

```

---

• 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:

```go

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

runPlainMode()

return

}

```

---

| Reference | Contents |

|-----------|----------|

| [Shell Scripts](references/shell-scripts.md) | Gum, VHS, Mods, Freeze, Glow - complete |

| [Go TUI](references/go-tui.md) | Bubble Tea patterns, debugging, anti-patterns |

| [Infrastructure](references/infrastructure.md) | Wish, Soft Serve, teatest, x/term |

| [Component Catalog](references/component-catalog.md) | All Bubbles components API |

| [Advanced Patterns](references/advanced-patterns.md) | Theming, layouts, production architecture |