Charmbracelet

Default Build Strategy

1. Start with Bubble Tea when the user asks for a TUI, terminal UI, dashboard, picker, wizard, or interactive CLI.
2. Add Bubbles instead of rebuilding common widgets by hand.
3. Add Lip Gloss once layout or visual hierarchy matters.
4. Add Huh when the interaction is form-heavy.
5. Add Glamour when the app renders markdown content.
6. Add Log for diagnostics, background jobs, or server logs.
7. Add Wish only when the app should run over SSH.

Core Rules

• Keep business logic separate from the Bubble Tea model.
• Do I/O in tea.Cmd, not directly in Update or View.
• Handle resize with tea.WindowSizeMsg and keep layouts responsive.
• Request background color with tea.RequestBackgroundColor when styles depend on light/dark mode.
• In Bubble Tea v2, declare terminal behavior in tea.View fields like AltScreen and MouseMode.
• In standalone Lip Gloss or Glamour output, print with Lip Gloss writers so color downsampling works.
• In Wish apps, remember middleware runs in reverse declaration order.
• In Bubble Tea apps, write logs to stderr or a file, not to stdout.

Bubble Tea First Skeleton

package main

import tea "charm.land/bubbletea/v2"

type model struct{}

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.KeyPressMsg:
        switch msg.String() {
        case "q", "ctrl+c":
            return m, tea.Quit
        }
    }
    return m, nil
}

func (m model) View() tea.View {
    v := tea.NewView("Hello from Bubble Tea")
    return v
}

Read These Next

• Read references/bubbletea-core.md for Bubble Tea's model, commands, messages, and program lifecycle.
• Read references/bubbletea-patterns.md for app structure, async work, Cobra integration, and multi-model composition.
• Read references/troubleshooting-workarounds.md before migrating old Charmbracelet code or mixing stale examples with v2 code.