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 valueflags, 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
--jsonmode 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.Envcarries 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)isRun(New(env), env);Runlets 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.runpasses 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.TestJSONEverywherewalks 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.
--versionis supported. - Aliases are cobra aliases (
add/set,get/read, andepoch statusforepoch 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. runtakes 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
PersistentPreRunEand command annotations: the agent nudge forreturnsValuecommands, the fresh-clone registration offer fortouchesVaultcommands, strict hygiene forrunandinject. - Secret values are never positional arguments:
cli.NoSecretArgsis 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
devsubcommands moved under cobra unchanged, with their own exit codes kept apart as unexporteddevExit*constants. Cobra'scompletioncommand 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.mdis 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 ofcore/). Startup cost is small;TestRunStartupBudgetbounds the time fromExecuteto starting a child for arunwithout references. - Shell completions remain to be specified; the hidden
completioncommand is the hook for them.
Alternatives considered
- The standard
flagpackage, 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 valueexamples directly.