92 lines
3.4 KiB
Markdown
92 lines
3.4 KiB
Markdown
# Command line reference
|
|
|
|
CommandKit owns command routing and syntax for commands registered with its
|
|
`App`. The caller supplies argv without the executable name, a context, and the
|
|
output and diagnostic writers. `App.Execute` returns an `Outcome`; it does not
|
|
exit the process.
|
|
|
|
## Help
|
|
|
|
The root help command lists registered commands and their summaries. Help is
|
|
available through a bare invocation, `--help`, `-h`, and `help`:
|
|
|
|
```text
|
|
example
|
|
example --help
|
|
example -h
|
|
example help
|
|
example help config show
|
|
example config --help
|
|
```
|
|
|
|
`help [COMMAND...]` resolves an exact registered path. A command group without
|
|
an execution handler displays its help when invoked by itself. A runnable
|
|
command with children runs its handler when invoked without help; add `--help`
|
|
to inspect that command and its children.
|
|
|
|
Help uses registered descriptions, command summaries, local flags, defaults,
|
|
required and repeatable flag metadata, and operand names and counts. It does not
|
|
construct the selected command's input or invoke its handler. Supplied flag and
|
|
operand values are still parsed so malformed values and unknown flags remain
|
|
usage errors. Missing execution-required values and input-combination checks
|
|
are skipped for help.
|
|
|
|
## Version
|
|
|
|
`version` reports the application identity by default:
|
|
|
|
```text
|
|
example version
|
|
example version --scope commandkit
|
|
example version --format yaml
|
|
```
|
|
|
|
The supported flags are:
|
|
|
|
| Flag | Values | Default | Meaning |
|
|
| --- | --- | --- | --- |
|
|
| `--scope` | `app`, `commandkit` | `app` | Select the caller's application identity or the embedded CommandKit module identity. |
|
|
| `--format` | `text`, `yaml` | `text` | Select the output format. |
|
|
|
|
Text output is `NAME VERSION`, followed by ` (REVISION)` when the selected
|
|
identity has a revision. An empty application version is displayed as `dev`;
|
|
the revision remains empty when omitted.
|
|
|
|
CommandKit identity uses the version of its module in build information. A
|
|
versioned module replacement supplies the effective version. A local or
|
|
versionless replacement, an untagged module, or missing build information
|
|
displays `dev`. The CommandKit identity name is `CommandKit`; dependency build
|
|
metadata does not supply a revision.
|
|
|
|
YAML output uses these explicit fields, including an empty revision:
|
|
|
|
```yaml
|
|
name: ExampleApp
|
|
version: dev
|
|
revision: ""
|
|
```
|
|
|
|
## Registered command syntax
|
|
|
|
Options are parsed after the complete command path and may be interspersed with
|
|
declared operands. Flags are local to the selected command. Use `--` to end
|
|
option parsing; all later tokens are operands.
|
|
|
|
Value flags accept `--name value` and `--name=value`. Boolean flags accept
|
|
presence as true and explicit values such as `--enabled=false`. A singleton
|
|
flag accepts repeated occurrences; the last successfully parsed occurrence
|
|
supplies its value. Every supplied occurrence is converted, so an earlier
|
|
malformed value remains an error. Repeatable flags preserve occurrence order,
|
|
with each occurrence treated as one value, including strings containing commas.
|
|
|
|
Typed inputs keep supplied state separate from defaults. An explicit empty,
|
|
false, or zero value is supplied. Help and version are available without
|
|
constructing application command inputs.
|
|
|
|
## Outcome status
|
|
|
|
CommandKit usage failures use status `2`; operational failures use status `1`.
|
|
Successful operations use status `0`. Application handlers may return a domain
|
|
classification and status of their choice, which `Execute` preserves. The caller
|
|
chooses how to map an outcome to process exit.
|