The Charm ecosystem

Choose the right Charm library or CLI for a terminal project, get the v2 charm.land import paths and pinned versions, and see how the pieces fit together before reaching for a library skill.

Charm publishes Go libraries for terminal programs and a set of CLIs built on them. The core v2 UI libraries import from charm.land; supporting libraries can still use GitHub module paths. 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. github.com/charmbracelet/<name> paths for the UI libraries mean the pre-v2 APIs; keep them unless the user asks to migrate, and then follow "Migrating from v1".
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 and versions

The versions above, except Wish, are pinned in the example module. Wish is listed for orientation only. It is not a dependency of the example module, and this repository has no SSH example.

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, and a v2 Log or Glamour needs v2 Lip Gloss.

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 Bubble Tea, Bubbles, Huh, and Lip Gloss in one step, since they share tea.Model, tea.Cmd, and lipgloss.Style; Log and Glamour only need a matching Lip Gloss major. Start by replacing github.com/charmbracelet/X with charm.land/X/v2 for bubbletea, bubbles, lipgloss, huh, glamour, and log; 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

• Passing v1 and v2 values of the same library across an API boundary. A v1 lipgloss.Style will not satisfy a v2 signature and vice versa.
• 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).