Welcome to today's Go Fan review! 🐹 I'm diving deep into github.com/charmbracelet/huh — the terminal forms library used throughout gh-aw for interactive TUI prompts. This one is extra exciting because huh just shipped v2.0.0 nine days ago with a new import path!

Module Overview

charmbracelet/huh is the Charmbracelet ecosystem's terminal form library. It provides interactive TUI components — inputs, selects, multi-selects, confirm dialogs, text areas, and spinners — built on top of Bubble Tea. It's what makes the gh aw create --interactive and gh aw run --interactive experiences feel polished.

Current Usage in gh-aw

• Version: v0.8.0 (released 2025-10-14)
• Files: 11 Go files across pkg/console/ and pkg/cli/
• Import Count: 11 imports

Key APIs in use:

Research Findings

// Before
import "github.com/charmbracelet/huh"

// After
import "charm.land/huh/v2"

// Before
form.WithTheme(huh.ThemeCharm())

// After  
form.WithTheme(huh.ThemeCharm(false)) // auto-detects terminal dark mode

form.WithViewHook(func(v tea.View) tea.View {
    v.AltScreen = true
    return v
})

Improvement Opportunities

🚨 Migrate to charm.land/huh/v2

This is the most important finding. The project already migrated to:

• charm.land/bubbles/v2 (PR feat: migrate charmbracelet/bubbles to v2 (charm.land/bubbles/v2) #21520, merged yesterday!)
• charm.land/bubbletea/v2
• charm.land/lipgloss/v2

Since huh v2 is built on Bubble Tea v2, keeping github.com/charmbracelet/huh at v0.8.0 (which uses the old Bubble Tea v1 API) alongside charm.land/bubbletea/v2 creates a split-brain situation in the dependency tree. The migration path is well-documented in the UPGRADE_GUIDE_V2.md.

The upgrade primarily involves:

1. Changing the import path from github.com/charmbracelet/huh → charm.land/huh/v2
2. Updating the go.mod entry
3. Handling the new theming API if custom themes are used (this project uses default theme, so likely no changes needed)

🏃 Quick Wins

• confirmExecution swallows errors silently (run_interactive.go:355): When form.Run() returns an error (e.g., Ctrl+C / ErrUserAborted), the function logs it but returns false. This means user cancellation and actual errors look the same to callers. Consider returning the error to distinguish intent.

• engine_secrets.go has 3 near-identical secret input forms (lines ~296, ~344, ~397): Three separate NewForm(NewGroup(NewInput().EchoMode(EchoModePassword)...)) blocks with similar structure. After the v2 migration, these could be consolidated into a helper function.

✨ Feature Opportunities

• View Hooks for the large workflow creation form (interactive.go): The 4-group form in promptForConfiguration() is the most complex form in the codebase. Using WithViewHook to enable AltScreen would prevent terminal scroll artifacts and provide a cleaner full-screen experience during the multi-step wizard.

• Automatic dark mode theming: huh v2's built-in themes auto-detect terminal background color. Currently no custom theme is set, but explicitly using huh.ThemeCharm(isDark) after v2 migration would make the forms look better in both light and dark terminals.

📐 Best Practice Alignment

• Accessible mode usage is already exemplary: Every single form in the codebase applies .WithAccessible(console.IsAccessibleMode()) at the form level. This is exactly what huh v2 recommends. No changes needed here. ✅

• Option construction is idiomatic: Using huh.NewOption(label, value) throughout is the correct pattern. ✅

• Filtering on select: Using .Filtering(true) for workflow selection is great UX. ✅

Recommendations

1. High priority: Migrate github.com/charmbracelet/huh → charm.land/huh/v2 — the Charmbracelet v2 migration train has already left the station for bubbles/bubbletea/lipgloss; huh is the remaining piece.

2. Medium priority: Refactor the 3 duplicate secret input forms in engine_secrets.go into a shared helper function.

3. Low priority: Explore WithViewHook for the complex workflow creation form in interactive.go to enable full-screen rendering.

Next Steps

• Open a PR to migrate github.com/charmbracelet/huh → charm.land/huh/v2 (following the same pattern as feat: migrate charmbracelet/bubbles to v2 (charm.land/bubbles/v2) #21520)
• Refactor duplicate EchoModePassword input forms in engine_secrets.go
• Explore View Hooks for the interactive workflow creation wizard

Generated by Go Fan 🐹
Module summary saved to: scratchpad/mods/charmbracelet-huh.md
Workflow run: §23233546981

AI generated by Go Fan · history

• expires on Mar 19, 2026, 7:26 AM UTC