# golang-cli Design Document | | | | --- | --- | | **Status** | Describes shipped behavior as of `v1.2.0` | | **Author** | Pim van Pelt `` | | **Last updated** | 2026-06-05 | | **Audience** | Contributors, and authors of CLIs built on this library | The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are used as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119), and are reserved for requirements enforced in code. Plain-language "can"/"will"/ "does" are descriptive, not normative. ## Summary `golang-cli` builds network-daemon-style CLIs: an interactive shell with tab-completion and `?`-help, plus a one-shot mode for scripts, both driven by one declarative command tree. It is the shared core extracted from `evpnc` (`vpp-evpn`) and `maglevc` (`vpp-maglev`), which had each grown their own copy. It is generic over a *client* type, and renders command output as colorized text or JSON from the same code. ## Goals 1. **One tree, one truth.** Dispatch, help, and completion all derive from a single command tree, so they cannot drift. 2. **Type-safe over any backend.** Command code receives its concrete client, no runtime type assertions. 3. **Drop-in for `evpnc` and `maglevc`** with no functional regression. 4. **Low ceremony.** A tree and a `main()` in a few lines, not a copied file. 5. **Text or JSON** from the same command code. 6. **Linux and OpenBSD** are both first-class. ## Non-Goals - Not a flag parser (uses stdlib `flag`) and not a TUI toolkit. - Does not own transport: it never dials, connects, or speaks a wire protocol. - Defines no command set, no output format — those are the caller's. - Holds no state beyond two process-global render switches (color, format). ## Functional Requirements **FR-1 Command tree and resolution** - **FR-1.1** The command set MUST be one tree of `Node[C]`; dispatch, `?`-help, and completion MUST all derive from it, with no second command table. - **FR-1.2** `Walk` MUST prefer a fixed child over the slot child, matching fixed by exact word then unique prefix. - **FR-1.3** A unique-prefix token MUST resolve to that child; an ambiguous prefix MUST NOT resolve. - **FR-1.4** A node MAY both run and have children. - **FR-1.5** A slot node (`Dynamic != nil`) MUST capture any token as an argument; captured args MUST reach the matched node's `Run` in order. - **FR-1.6** An unconsumable token MUST be returned to the caller and reported as an unknown-command error naming the first bad token, not anchored at the root. - **FR-1.7** At most one slot child per node is reachable; `Validate` SHOULD flag more than one. **FR-2 Completion and help** - **FR-2.1** `Dynamic` MUST receive the args captured by earlier slots, so candidates can depend on tokens already typed. - **FR-2.2** Completion MUST offer fixed children and slot values that have the partial token as a prefix. - **FR-2.3** If a confirmed token is unknown, completion MUST offer nothing. - **FR-2.4** Each completion/`?` `Dynamic` call MUST be timeout-bounded (default 1s). - **FR-2.5** `?` MUST list the reachable runnable paths with help and live slot values, without submitting the line. **FR-3 Shell and one-shot** - **FR-3.1** No positional args MUST start the REPL; positional args MUST run one command and exit. - **FR-3.2** A command MUST be able to stop the REPL by returning `ErrQuit`. - **FR-3.3** A REPL command error MUST be printed and MUST NOT stop the loop; a one-shot command error MUST exit non-zero. - **FR-3.4** `Ctrl-C` MUST abandon the line and continue; `Ctrl-D` MUST exit. **FR-4 Output** - **FR-4.1** A command MUST be able to describe one result once and have it rendered as text or JSON per a process-global format (`Emit`). - **FR-4.2** In JSON mode the framework MUST marshal the command's machine value; supplying it is the command's responsibility. - **FR-4.3** With color off or JSON selected, no ANSI escapes MUST be emitted. - **FR-4.4** Color MUST default on in the shell, off one-shot; `-color` overrides; `-json` forces it off. **FR-5 `App` entry point** - **FR-5.1** `App` MUST register `-color`, `-json`, `-version`, and `-server` (only when a server is configured). - **FR-5.2** `App` MUST NOT dial anything; the client is built in a caller's `Connect` callback. - **FR-5.3** `-version` MUST print and exit without connecting. - **FR-5.4** The server address MUST resolve from `-server`, else the configured env var, else the configured default. **FR-6 Authoring helpers** - **FR-6.1** `For[C]()`/`Builder` MUST build the tree without repeating `[C]` per node, returning plain `*Node[C]` so builder and literal construction mix. - **FR-6.2** `Validate` MUST report: >1 slot child per node, an empty word on a non-root node, duplicate fixed words among siblings, and a node that neither runs nor has children; it MUST handle circular slots without looping. **FR-7 Cancel-on-keypress (`keypress` subpackage)** - **FR-7.1** A streaming command MUST be able to cancel a context on any keypress. - **FR-7.2** When stdin is not a terminal, it MUST NOT consume input or cancel spuriously; it MUST just wait on the context. - **FR-7.3** It MUST use cbreak mode (single keystroke, echo off, output post-processing intact) and MUST restore the terminal on return. ## Non-Functional Requirements - **NFR-1** The library MUST be generic over the client type `C`; no `any`-typed clients, no reflection on the client. - **NFR-2** `Builder`, `App`, and `Emit` MUST be optional — a caller MUST be able to use struct-literal `Node`s with `Shell`/`Dispatch` directly. - **NFR-3** MUST build for `linux` and `openbsd` (SHOULD also for other BSDs and macOS). The OpenBSD `readline` termios workaround MUST be transparent and a no-op elsewhere. - **NFR-4** Core dependencies MUST be only `chzyer/readline` and `golang.org/x/sys` — no gRPC, protobuf, or web dependency. - **NFR-5** Releases MUST be semver tags; the import path is stable across `v0`/`v1`; a breaking `v2` MUST use the `/v2` suffix. - **NFR-6** Requires Go 1.25+ (generics with methods on generic types). - **NFR-7** `make check` (gofmt, vet, golangci-lint, tests) MUST pass before a commit; new behavior SHOULD ship with a server-free test. ## Architecture ``` argv ──▶ App.Run ──┬─ no args ─▶ Shell.Run ─▶ readline loop ─▶ Dispatch ─▶ Node.Run │ ▲ ▲ │ Completer ─┘ └─ '?' listener └─ args ─────────▶ Dispatch ───────────────────────────▶ Node.Run ``` Both modes share everything below `Dispatch`. Completion and `?` read the same tree the dispatcher walks (FR-1.1) — that is what keeps them from drifting. ## Open Questions - **Quoted arguments.** Tokenizing is `strings.Fields`, so no argument can contain a space; a shell-style splitter would be needed for quoted values. - **Output sink.** `Emit` writes to `os.Stdout`; an injectable `io.Writer` would make ported commands' output unit-testable. Not needed yet. - **JSON errors.** One-shot errors print as text on stderr even under `-json`; `{"error": "..."}` may be worth it once a consumer needs it.