Charm Ecosystem

Charm Ecosystem

The architect's guide to charmbracelet's terminal UI ecosystem. Individual charm-* skills teach HOW to use each library. This skill teaches WHICH libraries to combine and WHY.

$ARGUMENTS context: If a specific project type or library question is mentioned, focus on that decision path.

Ecosystem Map

Go Libraries (code you import)

CLI Tools (binaries you run)

Dependency Hierarchy

ultraviolet (cell-level primitives)
  |
  +-- lipgloss v2 (styling, layout, composition)
  |
  +-- bubbletea v2 (framework: Elm architecture, commands)
        |
        +-- bubbles v2 (components: spinner, list, table, viewport...)
        |     |
        |     +-- harmonica (physics animations, optional addition to any bubbletea app)
        |     +-- lipgloss v2 (component styling)
        |
        +-- huh v2 (forms, standalone or embedded in bubbletea)
              |
              +-- bubbles v2 (huh uses bubbles internally)
              +-- lipgloss v2 (theming)

Go libraries: charm.land/* vanity imports. CLI tools: github.com/charmbracelet/* or Homebrew.

Decision Tree

"I want to build a full TUI app"

Use: bubbletea + lipgloss + bubbles

The standard stack. Bubbletea provides the Elm architecture runtime, lipgloss handles all styling and layout, bubbles gives you pre-built components (list, table, viewport, spinner, textinput, progress, etc).

Add huh if you need form flows. Add harmonica if you need animated transitions.

"I want shell script UI / interactive bash prompts"

Use: gum

No Go code needed. Gum provides choose, filter, input, confirm, spin, style, join, file, pager, table, log. All output to stdout for shell capture.

"I want terminal forms"

Go app: huh (standalone or embedded in bubbletea) Shell script: gum (input, choose, confirm commands)

Huh runs standalone with .Run() for simple cases, or embeds in bubbletea as a tea.Model for complex apps. Use gum when you're in bash/zsh and don't want to write Go.

"I want to render markdown in the terminal"

Programmatically (Go code): glamour View files from CLI: glow

Glamour is a library - import it, call glamour.Render(). Glow is a tool - run glow README.md.

"I want animations in my TUI"

Use: harmonica + bubbletea

Harmonica provides spring (damped oscillator) and projectile physics. Drive with tea.Tick at 60fps. Create NewSpring once, call Update per frame.

"I want an SSH-accessible TUI"

Use: bubbletea + wish

Wish (not covered by individual skills) wraps bubbletea for SSH serving. Wish provides SSH middleware that wraps your bubbletea handler per-connection. See the wish repo for setup.

"I want to record terminal demos"

Use: vhs (optionally with gum for the demo content)

Write a .tape script with Type/Enter/Sleep/Wait commands. VHS renders to GIF/MP4/WebM. Use gum commands in your tape for pretty interactive demos.

"I want terminal screenshots"

Use: freeze

Pipe code or use --execute to capture command output. Outputs PNG/SVG/WebP with syntax highlighting, window decorations, shadows.

"I want a CLI framework with styled help"

Use: fang + cobra

Fang wraps Cobra - you still write *cobra.Command structs. Fang adds lipgloss-styled help, auto version from build info, manpage generation, signal handling.

"I want to send emails from the terminal"

Use: pop

TUI and CLI modes. Supports SMTP and Resend API. Pipe body from stdin, attach files.

"I need cell-level terminal control"

Use: ultraviolet (only if bubbletea is insufficient)

Low-level primitives: cell buffers, screen management, input decoding. Powers bubbletea and lipgloss internally. Unstable API. Only use for custom renderers or framework-building.

Architecture Patterns

The Elm Architecture for Go Developers

Bubbletea follows The Elm Architecture (TEA), a unidirectional data flow:

1. Model - a struct holding ALL application state (like a Redux store)
2. Update(msg) -> (model, cmd) - pure function: receives a message, returns new state + side effect
3. View(model) -> string - pure function: renders state to terminal output
4. Cmd - a function that performs I/O and returns a Msg back to Update

The runtime owns the loop. You never mutate state outside Update, never call View yourself, never do I/O in Update.

Go-specific mental model: think of it like an HTTP handler. The request is a Msg, the response is the new model + a Cmd to run next. The framework calls your handler, not the other way around.

Parent-Child Component Composition

Children are just fields on the parent model. Each child has its own Update/View. Parent delegates:

type parent struct {
    header textinput.Model
    body   viewport.Model
    footer help.Model
}

func (p parent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    var cmds []tea.Cmd

    // Forward to all children, collect commands
    var cmd tea.Cmd
    p.header, cmd = p.header.Update(msg)
    cmds = append(cmds, cmd)

    p.body, cmd = p.body.Update(msg)
    cmds = append(cmds, cmd)

    return p, tea.Batch(cmds...)
}

Children self-filter messages (spinners ignore wrong IDs, unfocused inputs ignore keys). Forward everything, let children decide.

Message Passing Between Components

Components communicate through the parent via typed messages:

// Child emits a "done" message
type formDoneMsg struct{ name string }

// Parent catches it and routes to another child
case formDoneMsg:
    m.body.SetContent("Welcome, " + msg.name)
    m.state = stateMain

No direct child-to-child communication. Always go through the parent's Update.

When to Use What

v2 Migration Quick Reference

The ecosystem moved from github.com/charmbracelet/* to charm.land/* vanity imports.

bubbletea v1 -> v2

lipgloss v1 -> v2

bubbles v1 -> v2

huh v1 -> v2

glamour v1 -> v2

Integration Cookbook

Five multi-library combinations with working code. See references/cookbook.md:

1. Standard TUI app - bubbletea + lipgloss + bubbles (list with styled header/footer)
2. Forms in TUI - bubbletea + huh (form then result display)
3. Markdown viewer - bubbletea + glamour + viewport (scrollable rendered markdown)
4. Animated transitions - bubbletea + harmonica (spring-animated position)
5. Scripted demo - gum + vhs (tape file demoing a gum script)

Checklist

• Import paths use charm.land/*/v2 (not github.com/charmbracelet/*)
• harmonica still uses github.com/charmbracelet/harmonica (no vanity import)
• ultraviolet still uses github.com/charmbracelet/ultraviolet (no vanity import)
• View returns tea.NewView(s) not raw string (bubbletea v2)
• AltScreen/MouseMode set in View, not as Program options (bubbletea v2)
• Colors use lipgloss.Color() function, not type literal (lipgloss v2)
• WindowSizeMsg handled for responsive layout
• huh forms embedded via Init/Update/View, not .Run(), when inside bubbletea