commandkit/docs/adr/0006-command-grammar.md

# 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 reference](../cli.md) owns operation-specific command signatures and
examples for implemented commands.