5.6 KiB
ADR 0006: Apply common command grammar and recommend shared vocabulary
Status
Proposed
Date
2026-10-06
Context
CommandKit owns routing, parsing, and help for standard and registered application commands. The selected registry and typed-input model supply a shared source for syntax metadata. A concrete grammar makes option placement, operands, repetition, and help predictable across the application suite. Shared vocabulary also reduces the need to remember different verbs for equivalent operations.
ADR 0001 establishes namespace-first ownership, typed bindings, explicit presence, and fresh invocation inputs. The remaining choices concern option placement, operand handling, repetition, and discovery behavior across registered commands.
Decision
CommandKit's standard grammar and vocabulary are part of the contract for CommandKit-owned commands. Its shared dispatcher and binding APIs implement that grammar, so application-owned commands registered through those APIs receive the same parsing mechanics. Applications retain ownership of their command names, operand meanings, and domain behavior.
CommandKit's documentation recommends the same grammar and vocabulary for
application-owned commands, including commands implemented outside its dispatcher.
Applications are encouraged to use standard verbs such as help, list, and
show where their operations have the corresponding purposes described in
ADR 0004.
CommandKit parses options after the complete registered command path. Within the selected command, options and declared operands may be interspersed. Operand counts and types come from registration; custom operand domain meaning belongs to the handler.
Standard options use lowercase names with hyphen-separated words and the --
prefix. Value options accept --name value and --name=value. Boolean options
accept their documented presence form and explicit values such as --name=false.
The -- token ends option parsing; subsequent tokens are operands.
Registered metadata identifies each flag as singleton or repeatable. A singleton accepts one occurrence per invocation. Repetition across either supported spelling is a usage error. A repeatable flag accumulates values in invocation order. Presence is recorded independently of defaults and values, preserving supplied empty strings, false, and zero under the existing typed-input decision.
CommandKit validates paths, flag names, conversions, operand counts, and declared input combinations through the shared parser. Those failures use the usage classification in ADR 0005. Registered domain value parsers and handlers receive values through the typed binding contract.
Root help is available through app, app help, app --help, and app -h.
Invoking a command group with no registered execution handler displays group help.
A runnable command follows its registered handler and operand requirements,
including when it also has subcommands. CommandKit-owned groups such as config
display help on bare invocation. app help COMMAND ... and a resolved command's
--help display the same registered help. Required execution operands are checked
for execution requests; help uses resolved command and flag
metadata. Invalid paths and flag names receive usage diagnostics.
app version and the root-only app --version shortcut report application version.
The version command also accepts explicit component selection under
ADR 0004.
Standard configuration operations have declared flag inputs. PromptKit collection
and definition commands declare their resource and ID operands. The registry
generates help, including supported formats and selector applicability, from
those declarations.
The internal Cobra/pflag adapter implements this grammar using registered
metadata and backend parsing mechanisms. Flag values beginning with - follow
their registered type and supported value syntax. Parser adaptation is centralized
at that boundary, following ADR 0002.
Alternatives considered
| Alternative | Analysis |
|---|---|
| Flags before all operands | Gives argument order a simple positional rule. Operators organize values around that rule when assembling commands. |
| Common flags before or between command-path components | Supports familiar global-option styles. Routing and help need rules for options across several command levels. |
| Last singleton occurrence wins | Supports layered argv construction. Repeated assignments become an override mechanism requiring separate presence and precedence interpretation. |
| Application-selected parser conventions | Supports existing CLI implementations. Operators and shared help need per-application syntax knowledge. |
Consequences
Operators learn one option placement and repetition policy for adopting commands using CommandKit. Custom handlers retain their operand domain contracts. Typed bindings and metadata support consistent parsing and generated help. Shared vocabulary guidance encourages consistent names for equivalent application-owned operations.
The adapter carries the work needed to preserve the grammar across dependency
updates. Contract evidence must cover repetition, mixed spellings, explicit
presence, interspersed operands, --, help, and fresh state. Backend replacement
preserves the selected grammar under the release compatibility policy.
The CLI reference owns detailed command signatures and examples when implemented. This record owns the common rules that apply across those signatures.