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.Filehandles of the terminalinternal/ttyopened, 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 ontty.Terminaland 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
--jsonoutput. cmd/vaultfoldgains about twenty indirect modules and itsgoline rises to Huh's floor (1.25.8 for v2.0.3);coreis 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 buildofcmd/vaultfoldwith 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.Newpicks the renderer once; the accessible renderer is line based ontty.Terminaland 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" throughSession.StepsandBeginStep. 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/promptsitself via a Node helper. Rejected: Node is not a runtime dependency of the CLI (ADR 0013).