79 lines
3.9 KiB
Markdown
79 lines
3.9 KiB
Markdown
# 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](0004-standard-inspection-surface.md).
|
|
|
|
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](0001-command-dispatch-and-inputs.md).
|
|
|
|
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](0005-invocation-outcomes.md).
|
|
|
|
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 roadmap](../roadmap/01-cli-plan.md) tracks operation-specific syntax;
|
|
the CLI reference will own detailed command signatures and examples when
|
|
implemented.
|