跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
安全

charmed-huh

Build terminal forms and interactive prompts in Go with Huh v2 (charm.land/huh/v2, charmbracelet): input, text, password, select, multiselect, confirm, note, and file picker fields grouped into pages, with validation, dynamic fields, themes, accessible mode, and a spinner for follow up work. Use when asking a user questions from a CLI, building a wizard, survey, or yes or no question, either standalone with Run or embedded in a Bubble Tea v2 program. Not for shell scripts (charmed-gum) or free form TUIs (charmed-bubbletea).

tpscloud · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add tpscloud/charmedimsure --skill charmed-huh

技能说明


name: charmed-huh description: "Build terminal forms and interactive prompts in Go with Huh v2 (charm.land/huh/v2, charmbracelet): input, text, password, select, multiselect, confirm, note, and file picker fields grouped into pages, with validation, dynamic fields, themes, accessible mode, and a spinner for follow up work. Use when asking a user questions from a CLI, building a wizard, survey, or yes or no question, either standalone with Run or embedded in a Bubble Tea v2 program. Not for shell scripts (charmed-gum) or free form TUIs (charmed-bubbletea)." license: "MIT"

Huh v2

Build terminal forms and prompts in Go with Huh v2: typed fields, validation, dynamic options, themes, accessible mode, and forms embedded in Bubble Tea.

Import as "charm.land/huh/v2"; the spinner is "charm.land/huh/v2/spinner". Pinned and verified against v2.0.3. Go blocks headed // examples/... are trimmed from complete programs that build against the pinned modules; // excerpt blocks are API sketches.

If the project's go.mod still requires github.com/charmbracelet/huh (pre-v2), the v2 APIs here do not apply. Use go doc against the project's version and keep its import paths unless the user asks to migrate.

Workflow

  1. Declare a variable for each answer.
  2. Build fields with a Title and Value(&v) (or a Key), add Validate where input must be checked, and put them into pages with NewGroup.
  3. Choose output and mode: WithOutput(os.Stderr) when stdout carries results; call WithAccessible only when ACCESSIBLE is set.
  4. Standalone, call form.Run() and handle huh.ErrUserAborted (exit 130) and other errors. Inside Bubble Tea, embed the form instead.
  5. Check the bound values after Run; accessible mode returns nil without running validation on EOF.
  6. Try it in a terminal: required fields, back navigation, ctrl+c, dynamic options, and once in accessible mode (TERM=dumb). Fix what fails and rerun.

Shape of a form

Form holds Groups; a group is one page of Fields. The user moves through fields with enter or tab (shift+tab back), and the form advances to the next group when every field on the page validates. Answers land in variables you bind with Value(&v).

The standalone example collects and prints a local task plan. From a repository checkout, run it in a terminal with cd examples && go run ./charmed-huh/standalone.

// examples/charmed-huh/standalone/main.go
var (
    projects []string
    tasks    []string
    location string
    confirm  bool
)

form := huh.NewForm(
    huh.NewGroup(
        huh.NewNote().
            Title("Local task planner").
            Description("Choose projects and tasks. Use _space_ to toggle, `/` to filter, *ctrl+a* for all."),

        huh.NewMultiSelect[string]().
            Title("Projects").
            Options(
                huh.NewOption("Website", "site").Selected(true),
                huh.NewOption("Documentation", "docs"),
            ).
            Filterable(true).
            Height(8).
            Validate(func(v []string) error {
                if len(v) == 0 {
                    return errors.New("pick at least one project")
                }
                return nil
            }).
            Value(&projects),

        huh.NewMultiSelect[string]().
            Title("Tasks").
            Options(huh.NewOptions("build", "test", "lint", "format")...).
            Value(&tasks),
    ).Title("What"),

    huh.NewGroup(
        huh.NewSelect[string]().
            Title("Working directory").
            Options(
                huh.NewOption("Current directory", "."),
                huh.NewOption("Parent directory", ".."),
            ).
            Value(&location),
    ).Title("Where"),

    huh.NewGroup(
        huh.NewConfirm().Title("Print task plan?").Affirmative("Print").Negative("Cancel").Value(&confirm),
    ),
)

err := form.Run()
switch {
case errors.Is(err, huh.ErrUserAborted):
    fmt.Fprintln(os.Stderr, "cancelled")
    os.Exit(130)                // ctrl+c
case err != nil:
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
}

Run blocks. The normal TUI renders to stderr; accessible prompts default to stdout. RunWithContext(ctx) adds cancellation to the TUI. A single field can run on its own: huh.NewInput().Title("Name").Value(&name).Run().

Options are Option[T] values: NewOption(label, value) for distinct labels, NewOptions(values...) when the label is the value. T is any comparable type, so selects can yield ints, enums, or struct keys directly.

Fields and validation

The fields are NewInput, NewText, NewSelect[T], NewMultiSelect[T], NewConfirm, NewNote, and NewFilePicker. All have Title and Description; all but Note take Value(&v), Validate, and Key. Passwords use NewInput().EchoMode(huh.EchoModePassword).

Read references/fields.md for the per field setter table, default key bindings and KeyMap, group layouts, and every form level option (WithTimeout, WithProgramOptions, WithViewHook, and the rest).

Built in validators for strings: ValidateNotEmpty(), ValidateMinLength(n), ValidateMaxLength(n), ValidateLength(min, max), ValidateOneOf(a, b, c). Validation runs when the field loses focus; a failing field blocks the page.

Groups and dynamic fields

NewGroup(fields...) with Title, Description, WithHide(bool), and WithHideFunc(func() bool) to skip a page based on earlier answers (see the dynamic example):

// examples/charmed-huh/dynamic/main.go
huh.NewGroup(
    huh.NewNote().
        TitleFunc(func() string { return "Details for " + project }, &project).
        Description("This examp
阅读完整来源 ↗