🐹 Go Fan Report: charmbracelet/huh — Terminal Form Library

Module Overview

charmbracelet/huh is the interactive form and prompt library at the heart of gh-aw's CLI UX. It powers every password input, workflow selection list, confirmation dialog, and the multi-step workflow builder wizard. Built on Bubble Tea, it provides Input, Text, Select, MultiSelect, and Confirm field types with theming and accessibility support.

Currently pinned: github.com/charmbracelet/huh v0.8.0 (Oct 2025)
Latest available: charm.land/huh/v2 v2.0.3 (released 2026-03-09, pushed 2026-03-30)

Current Usage in gh-aw

The module is used in 13 files across pkg/console/ and pkg/cli/.

• Files: 13 source files
• Import Count: 13 direct imports
• Key APIs Used: NewForm (19×), NewGroup (22×), NewOption (33×), NewSelect (8×), NewInput (8×), NewConfirm (5×), NewMultiSelect (2×), NewText (1×), EchoModePassword (4×)

Consistent patterns observed:

• Every form applies .WithTheme(styles.HuhTheme()).WithAccessible(console.IsAccessibleMode()) — nicely consistent
• Context-aware forms use form.RunWithContext(ctx) for cancellation support
• TTY detection guards all interactive code paths with non-interactive fallbacks
• Field validation is done inline with Validate(func(s string) error {...})

The standout usage is the 4-group workflow creation wizard in pkg/cli/interactive.go — it guides users through trigger selection, capability configuration (tools + safe-outputs multi-selects), network/security settings, and free-text instructions in a clean paginated flow.

Research Findings

Recent Updates

huh reached v2.0.0 on 2026-03-09 — a significant release that migrates the entire Charm ecosystem to vanity import paths and Bubble Tea v2. Here's what changed:

Best Practices from Maintainers

• Use ThemeFunc to detect dark/light terminal background automatically
• Set accessible mode at the form level (not field level) — gh-aw already does this correctly
• Use OptionsFunc with a binding for dynamic options that change based on other fields
• form.GetString("key") / form.GetInt("key") via .Key() for Bubble Tea embedded forms

Improvement Opportunities

🏃 Quick Wins

1. Upgrade to huh v2 — remove the lipgloss v1 orphan dependency

This is the most impactful and natural improvement. gh-aw has already migrated to:

• charm.land/bubbletea/v2 v2.0.2
• charm.land/lipgloss/v2 v2.0.2
• charm.land/bubbles/v2 v2.1.0

But github.com/charmbracelet/huh v0.8.0 still depends on github.com/charmbracelet/lipgloss v1.x — an old dependency that now exists solely because of huh. The code even has a comment acknowledging this forced redundancy:

// pkg/styles/huh_theme.go
// huh v0.8.0 depends on charmbracelet/lipgloss v1, not charm.land/lipgloss/v2.
// This file intentionally uses the v1 import to match huh's type expectations.
import "github.com/charmbracelet/lipgloss"  // v1 — only needed for huh compatibility
```

Upgrading to `charm.land/huh/v2` removes this entire class of problem. The import changes would be:
- `"github.com/charmbracelet/huh"` → `"charm.land/huh/v2"`
- `"github.com/charmbracelet/lipgloss"` (in `huh_theme.go`) → `"charm.land/lipgloss/v2"`

**2. Get v2.0.3 bug fixes for free**

`v2.0.3` fixes cursor visibility when navigating multiline `Select` options. This directly affects the `toolOptions` picker in `interactive.go` which uses `.Height(8)` and has multi-word labels like:
```
github - GitHub API tools (issues, PRs, comments, repos)

These could be cut off on navigation in v0.8.0. The fix is free with the upgrade.

✨ Feature Opportunities

3. ThemeFunc with dark mode detection

huh v2 introduces ThemeFunc = func(isDark bool) *huh.Styles. The current HuhTheme() in pkg/styles/huh_theme.go already uses lipgloss.AdaptiveColor for light/dark variants, but doesn't get the isDark bool signal from huh's terminal detection. Migrating to ThemeFunc would let the theme make better decisions:

// After upgrade — huh calls this with isDark detected from terminal
func HuhTheme(isDark bool) *huh.Styles {
    // Use isDark to pick more precise colors instead of AdaptiveColor
}

4. Dynamic OptionsFunc for deferred option loading

The buildSafeOutputOptions() function in interactive.go loads all safe output options eagerly before the form starts. For larger option sets, OptionsFunc with a binding enables lazy + cacheable loading:

huh.NewMultiSelect[string]().
    OptionsFunc(func() []huh.Option[string] {
        return buildSafeOutputOptions()
    }, nil). // nil binding = compute once and cache

📐 Best Practice Alignment

5. Theme return type

HuhTheme() currently returns *huh.Theme and is called as .WithTheme(styles.HuhTheme()). After the v2 upgrade it should return huh.ThemeFunc and be passed directly:

// Before (v0.8.0)
func HuhTheme() *huh.Theme { ... }
form.WithTheme(styles.HuhTheme())

// After (v2.0.x)
func HuhTheme(isDark bool) *huh.Styles { ... }
form.WithTheme(styles.HuhTheme)  // pass the function itself

6. Remove the lipgloss v1 workaround comment

Once upgraded, the explanation comment in huh_theme.go becomes obsolete and should be removed.

Recommendations

Next Steps

1. Check UPGRADE_GUIDE_V2.md in the huh repo for the complete migration checklist
2. Run go get charm.land/huh/v2@latest and update all import paths
3. Update HuhTheme() signature in pkg/styles/huh_theme.go to return huh.ThemeFunc
4. Remove github.com/charmbracelet/huh and github.com/charmbracelet/lipgloss (v1) from go.mod
5. Run go mod tidy — lipgloss v1 should disappear from the dependency tree

Generated by Go Fan 🐹 — §23939308349
Module summary saved to: scratchpad/mods/charmbracelet-huh.md

References:

• charmbracelet/huh releases
• huh v2.0.0 release notes
• huh v2 docs

AI generated by Go Fan · history

• expires on Apr 4, 2026, 8:16 AM UTC