4.2 KiB
ADR 0002: Use Cobra and pflag as the initial internal CLI backend
Status
Accepted.
Date
2026-10-06
Context
CommandKit's selected dispatcher model needs nested routing, flags and operands, generated help, usage diagnostics, and invocation execution. Reimplementing this generic infrastructure would add work beyond the suite-specific inspection and consistency behavior that motivates the library.
Decision
Use Cobra with pflag as the sole initial CLI backend. CommandKit translates its registrations into backend command trees, flag bindings, and execution callbacks. Reuse their routing, option parsing, help, context, and stream mechanisms and add adaptation where selected CommandKit semantics require it.
CommandKit retains its own public registration API, typed inputs, standard families, and observable contracts. Its public registration and handler APIs use CommandKit-owned definitions and typed inputs. Cobra commands and pflag getters stay within CommandKit's internal adapter. Independent consumer framework use remains application-owned. ADR 0003 records the adapter and root-owned public contracts.
Invocations do not inherit parsed values or presence from previous invocations. Rebuilding the backend command tree and input storage from registered definitions is the initial implementation strategy; safe reuse remains an implementation choice. CommandKit's tree construction uses registered metadata and leaves acquisition callbacks uninvoked. Application startup and callback effects retain their own lifecycle.
Implement one concrete backend. There is no initial public backend selector or pluggable framework. A future replacement can change internal implementation while preserving the public API and selected behavioral contracts.
Alternatives considered
| Alternative | Advantages | Reason not selected |
|---|---|---|
| urfave/cli v3 | Destination bindings for flags and named operands, presence queries, and duplicate controls fit the chosen input model closely. | Credible alternative; Cobra's broader adoption is the preferred maintenance tradeoff. |
| pflag alone | Established parsing with a smaller integration surface. | Leaves more routing, help integration, and command infrastructure to implement. |
| Kong | Compact typed-struct and tag-driven declarations. | Its main declaration model differs from the explicit-binding API; adaptation reduces its benefit. |
Standard flag alone |
Familiar variable binding and custom value parsing. | First-operand stopping requires adaptation for the intended syntax, with more custom command infrastructure. |
| Expose Cobra as the public API | Less adapter code and the full framework surface. | Couples consumers to backend structures and framework-specific configuration. |
| Interchangeable backends immediately | Future integration flexibility. | Adds abstraction and behavior surfaces without a current requirement. |
Consequences
The framework supplies established generic CLI machinery. CommandKit still owns registration conflicts, reserved families, typed bindings and presence, standard help and diagnostics, provider integration, and selected reports and outcomes.
The adapter must accommodate explicit empty/false/zero values, independent parsed state, selected repetition and operand rules, and help without configuration. Backend features do not expand the standard automatically: for example, completion commands remain deferred unless deliberately selected.
Backend error handling must preserve application outcomes, avoid duplicate diagnostics, and return control to the application's entry point.
The architecture policy owns normative boundaries. ADR 0001 records the dispatcher and input model.
Reviewed primary references from the selection: