Skip to content

0022: Interactive prompts with Huh on the controlling terminal

  • Status: accepted
  • Date: 2026-09-25

The number was assigned at merge of the cli-interactive-ux proposal into staging (this file was XXXX-interactive-prompts-huh.md until then), per that change's task 4.4.

Context

vaultfold's prompts are bare lines read by internal/tty from the controlling terminal. The user decided to adopt the interaction ideas of Bombshell's @clack/prompts (step markers, grouped flows, spinners with status, intro and outro framing, cancel-safe Ctrl-C) without adding Node to the CLI (ADR 0013), and to share styling with the planned Bubble Tea TUI (cli "Terminal UI"). The hard constraints come from the existing specs and design: prompts open the terminal device directly and never fall back to stdin or stdout (harness-integration "Out-of-band value collection"), secrets are never arguments (ADR 0018), stdout and stderr formats are pinned by goldens, --json prints exactly one document, and run has a startup budget.

Decision

  • Interactive prompts are built with Charm's Huh v2 (charm.land/huh/v2) in one package, cmd/vaultfold/internal/prompt, which is the only importer of Huh, Bubble Tea, Lip Gloss and Bubbles (enforced by a test).
  • Every form gets explicit input and output: the *os.File handles of the terminal internal/tty opened, set in one constructor, because Huh's and Bubble Tea's defaults are stdin and stdout.
  • Huh's own accessible mode and spinner are not used: the accessible mode treats end of input as the default and still emits styles, and the spinner takes the terminal into raw mode, which would swallow git or ssh credential prompts during sync. vaultfold provides a line-based accessible renderer on tty.Terminal and an output-only spinner.
  • One theme (brand teal and gold, adaptive to the background) is the styling source the TUI will reuse. Colour goes to the terminal only and is off under NO_COLOR, TERM=dumb, accessible mode, or a Windows console without virtual terminal processing.
  • Ctrl-C at a prompt restores the terminal, writes nothing and exits 130.

Details: openspec/changes/cli-interactive-ux/design.md.

Consequences

  • Prompts gain framing, grouped flows and progress without changing any stdout, stderr or --json output.
  • cmd/vaultfold gains about twenty indirect modules and its go line rises to Huh's floor (1.25.8 for v2.0.3); core is unaffected.
  • The terminal-only rule is now enforced by an import test, an AST test and a pty test that proves stdin is never read, instead of by convention alone.
  • A later change that wants Unicode glyphs must detect the console code page; markers are ASCII until then.
  • Measured binary size (darwin/arm64, Go 1.27.1, go build of cmd/vaultfold with default flags): the vaultfold binary was 18.75 MiB (19,664,274 bytes) at the parent of group 1 and 18.81 MiB (19,719,458 bytes) at group 1 (#95), a 53.9 KiB difference, because group 1 added the prompt package before any command linked it. At the head of group 4 the vaultfold binary is 25.01 MiB (26,226,914 bytes); that figure includes the daemon, browser and other work merged since, so it is not the cost of Huh alone.

Decisions taken during groups 1-4

  • Group 1: Session.New picks the renderer once; the accessible renderer is line based on tty.Terminal and never emits an escape byte.
  • Groups 2 and 3: Ctrl-C and every cancellation path restore the terminal and exit 130; single prompts on the remaining commands use the same Session as the grouped flows.
  • Group 4: an accessible selection never maps unmatched text to the default: it re-asks and, after three unmatched answers, fails with ErrInvalidChoice (numbers, exact names and unique prefixes are accepted). Steps are announced as "Step n of m" through Session.Steps and BeginStep. A handle that is not a real terminal, or a terminal that reports 0 columns or 0 rows, gets the accessible renderer, because the rich renderer redrew without end on a 0x0 pty.

Alternatives considered

  • Bubbles components in our own Bubble Tea models. Workable, and the fallback if Huh regresses explicit I/O; rejected for now because it rebuilds Huh's fields, validation, navigation and keymap.
  • Keep the line prompts and add colour only. Rejected: no grouped flows, no progress, and Ctrl-C at a hidden prompt would still leave the terminal without echo.
  • @clack/prompts itself via a Node helper. Rejected: Node is not a runtime dependency of the CLI (ADR 0013).