Skip to content

0018: CLI framework: cobra

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

Context

Before the implement-cli-v1 change, cmd/vaultfold had a hand-rolled dispatcher for four hidden dev subcommands. The cli spec asks for much more than a dispatcher can give cheaply:

  • a single binary with more than fifty commands, several of them nested (vault add, member revoke, hook install, collection new);
  • generated help that lists every command with a one-line description, including commands not yet built ("Help lists every command");
  • the closest command suggested for an unknown one ("Unknown command");
  • aliases (add/set, get/read);
  • per-command --help, GNU-style --flag value flags, and later shell completions;
  • run -- <cmd> [args...], where nothing after -- may be read as a vaultfold flag;
  • one exit code table (0 to 4) and a --json mode printing exactly one document on stdout, for every command.

The commands also have to be testable in process, with the terminal, environment, clock and child processes injected, as the dev commands already were.

Decision

The CLI is built on github.com/spf13/cobra (with spf13/pflag), per the implement-cli-v1 design.md section "CLI framework: cobra" and its "Decisions taken during group 2".

  • The tree is built by cli.New(env Env) *cobra.Command. Env carries every outside dependency (standard streams, passphrase reader, Now, Getenv, Environ, LookPath, IsTerminal, terminal, clipboard, child runner), so golden tests drive the real tree in process. Execute(env) is Run(New(env), env); Run lets tests add probe commands to a fresh tree.
  • Every command returns an error, and cli.ExitCode(err) maps typed errors to the exit code table in one place: 0 ok, 1 user error, 2 policy or verification failure, 3 locked identity, 4 backend or network failure. run passes its child's status through.
  • With --json, stdout carries exactly one envelope, {"ok":true,...} or {"ok":false,"error":{"code":...,"message":...}}; error codes are stable constants, and every warning goes to stderr. TestJSONEverywhere walks the cobra tree at run time and audits every visible command (group 13 decision 10).
  • Unknown commands always name the nearest visible command, even where cobra's own distance limit would suggest nothing. No arguments prints the help on stderr and exits 1. --version is supported.
  • Aliases are cobra aliases (add/set, get/read, and epoch status for epoch list).
  • Commands of the cli spec that this build does not implement are registered with a description ending "(not yet available)" and exit 1 with code not-available; they accept unknown flags so the refusal is their own message rather than a flag error.
  • run takes its child's argv only after --, so a child flag is never read as a vaultfold flag (group 10 decision 8).
  • Cross-cutting behavior hangs off the root's PersistentPreRunE and command annotations: the agent nudge for returnsValue commands, the fresh-clone registration offer for touchesVault commands, strict hygiene for run and inject.
  • Secret values are never positional arguments: cli.NoSecretArgs is the positional validator for commands whose secret comes from a prompt or --stdin, and its refusal never echoes the value (cobra's own argument errors would).
  • The hidden dev subcommands moved under cobra unchanged, with their own exit codes kept apart as unexported devExit* constants. Cobra's completion command is kept but hidden until shell completions are specified.

Consequences

  • Help, aliases, suggestions, nested subcommands and flag parsing come for free and behave the way users of kubectl, gh and docker expect; contributors and coding agents already know the library.
  • The command surface is data that tests can enumerate. The command table in cmd/vaultfold/README.md is checked against the cobra tree (TestReadmeCommandsMatchHelp), and the JSON audit covers new commands without being edited.
  • Some of cobra's defaults had to be overridden to meet the spec: the suggestion distance, no-argument behavior, argument errors that would echo a secret, and flags after --. Each override is pinned by a test.
  • Cobra and pflag are new dependencies of cmd/vaultfold (not of core/). Startup cost is small; TestRunStartupBudget bounds the time from Execute to starting a child for a run without references.
  • Shell completions remain to be specified; the hidden completion command is the hook for them.

Alternatives considered

  • The standard flag package, extending the existing dispatcher. Rejected: nested subcommands, suggestions, aliases and generated help for roughly fifty commands would all be re-implemented and maintained here, and the dispatcher had already shown that cost for four.
  • urfave/cli v3. It would also work. Rejected on familiarity and on pflag's GNU-style flags, which match the spec's --flag value examples directly.