3.8 KiB
ADR 0006: Apply common command grammar and recommend shared vocabulary
Status
Accepted.
Date
2026-10-06
Context
CommandKit owns routing, parsing, and help for standard and registered application commands. 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.
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.
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. For a singleton, the last occurrence supplies its value, including when the invocation mixes supported spellings. A repeatable flag accumulates values in invocation order. Presence follows the typed-input contract in ADR 0001.
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.
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 registered metadata. Invalid paths and flag
names receive usage diagnostics.
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. |
| Reject repeated singleton flags | Detects repeated assignments, but prevents callers from assembling defaults followed by explicit overrides. |
| 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. Shared vocabulary guidance encourages consistent names for equivalent application-owned operations.
The internal adapter must preserve the selected grammar across backend changes. The CLI reference owns operation-specific command signatures and examples for implemented commands.