The Charm ecosystem

This skill routes to the per-library charmed-* skills and their examples, which build against the pinned modules.

Workflow

1. Match the task to a row in "Which library" below and note the skills it names.
2. Check the project's go.mod against "Import paths". Keep pre-v2 paths unless the user asks to migrate.
3. Add the pinned versions with the go get command below.
4. Open the per-library skill for API detail and start from the example it links.
5. Run go test ./... in the application module. On a type mismatch between Charm libraries, run go list -m all and look for a v1 and v2 mix of the libraries that share types.

Import paths

For Bubble Tea, Bubbles, Lip Gloss, Huh, Glamour, and Log, the older github.com/charmbracelet/<name> paths belong to the pre-v2 APIs. This rule does not apply to colorprofile or Harmonica, which keep their GitHub module paths. Two major versions can coexist in one binary as separate modules, but the libraries that share types (Bubble Tea, Bubbles, Huh, Lip Gloss) have to move together: a v1 lipgloss.Style does not satisfy a v2 signature. A v2 Log or Glamour needs v2 Lip Gloss.

Pinned versions

Verified on 2026-10-12 and pinned in the example module, which also pins colorprofile v0.4.3 and Harmonica v0.2.0. From an existing application module, select the tested core UI versions with:

go get charm.land/bubbletea/v2@v2.1.0 charm.land/bubbles/v2@v2.2.1 \
       charm.land/lipgloss/v2@v2.0.6 charm.land/huh/v2@v2.0.3 \
       charm.land/glamour/v2@v2.0.1 charm.land/log/v2@v2.0.1

Which library

A full interactive program (panes, navigation, live data). Bubble Tea for the loop, Bubbles for the widgets, Lip Gloss for layout and color. Start from the compose or fullscreen example in charmed-bubbletea.

A CLI that asks a few questions then does work. Huh alone. Run the form, then a Huh spinner around the work. No Bubble Tea code needed.

Questions inside a larger TUI. Huh embedded as a bubble; see the embedded example in charmed-huh.

Pretty output from a non interactive command. Lip Gloss only: styles, tables, trees, printed with lipgloss.Println. Add Glamour if the content is Markdown. Add Log for the logging.

A shell script that needs prompts. gum (charmed-gum). Same widgets, no Go.

A demo GIF for the README. vhs (charmed-vhs).

Serve the TUI over SSH. Wish wraps a Bubble Tea program per connection; pass tea.WithEnvironment(session.Environ()) so color detection uses the client's terminal.

Animation. Harmonica springs; Bubbles' progress bar already uses it. For custom motion, tick with tea.Tick and step the spring on each tick.

How they fit together

ultraviolet, x/ansi, colorprofile      terminal I/O, escape codes, profiles
        │
   Bubble Tea ◄──── Lip Gloss           loop and rendering ◄── styles, layout
        │               │
     Bubbles            │                widgets styled by Lip Gloss
        │               │
       Huh ◄────────────┘                forms built from Bubbles
     Glamour ───► Lip Gloss              Markdown to ANSI, printed via Lip Gloss
       Log ─────► Lip Gloss              styled log lines

Data flows as strings. Lip Gloss Render returns a string; Bubbles' View returns a string; Glamour Render returns a string and an error, which you must handle. Your top level View wraps the assembled string in tea.NewView. There is exactly one place where terminal state is declared (fields on tea.View) and one place where color downsampling happens (the Bubble Tea renderer, or the lipgloss.Print family when there is no program).

Dark or light detection follows the same rule. Inside a program, return tea.RequestBackgroundColor and read IsDark() from the message; most Bubbles style constructors (DefaultStyles(isDark); table and filepicker take no argument) and every Huh theme take that bool. Outside a program, call lipgloss.HasDarkBackground(os.Stdin, os.Stdout) once before printing anything.

Recipes across libraries

• Themed app. One styles struct built from isDark, passed to every bubble's SetStyles or Styles field and to Huh's ThemeFunc. Build it in the BackgroundColorMsg handler.
• Markdown help screen. Glamour renders at the available width, and a Bubbles viewport scrolls it. The viewer example subtracts layout space from WindowSizeMsg.Width and clamps the result.
• Modal dialog. Lip Gloss layers and compositor over the main view; hit test clicks with Compositor.Hit (the overlay example).
• Long running work with progress. A Cmd that reads from a channel the worker writes to; each message updates a Bubbles progress model (combine the subscription pattern with the progress example).
• Debug logging in a TUI. tea.LogToFileWith("debug.log", "app", log.Default()), then tail the file. See the logging example.
• Tests. Drive Update with constructed messages; run the whole program with tea.WithInput, tea.WithOutput, tea.WithWindowSize, and tea.WithColorProfile(colorprofile.Ascii) for stable strings.

Migrating from v1

Move the libraries that share types in one step. Subpackages keep their suffix (bubbles/v2/list, lipgloss/v2/table).

Read references/migration.md for the per-library API changes (Bubble Tea keys, mouse, and view fields; Lip Gloss colors; Bubbles sizes and key maps; Huh themes; Glamour and Log), links to the pinned upstream upgrade guides, and the test loop to run after each step.

The CLIs

Where to look when a skill here is not enough

• The sibling skills and examples live in the repository; an isolated skill install does not include them. To run a linked example from a checkout, enter the examples directory and run go run ./charmed-bubbletea/compose (or the corresponding example).
• Module source: $(go env GOMODCACHE)/charm.land/<lib>/v2@<version>/. go doc -all charm.land/<lib>/v2 from any module that requires it.
• Upstream examples live in each GitHub repo under examples/ (not in the module zip for most libraries).

Mistakes that cost time

• Using @latest instead of the pinned versions. It selects versions these skills have not been checked against.
• Trusting upstream prose over go doc. Some READMEs and doc comments still show v1 signatures (View() string in Huh's README, tea.NewFrame in a Bubbles doc comment).