base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Add shared report format flag

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 03:45:12 +00:00
parent 3a6c66f550
commit 924692b541
18 changed files with 206 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/cli.md
View File

@@ -46,7 +46,7 @@ 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. |
| `--format` | `text`, `yaml`, `json` | automatic | Select the output format; automatic uses text for version. |
Text output is `NAME VERSION`, followed by ` (REVISION)` when the selected
identity has a revision. An empty application version is displayed as `dev`;
@@ -58,7 +58,7 @@ 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 and JSON output use these fields, including an empty revision:
```yaml
name: ExampleApp
@@ -111,6 +111,14 @@ caller passes result and diagnostic writers to `App.Execute`; substantive
results go to `Streams.Out`, and categorized messages, terminal explanations,
and usage guidance go to `Streams.Err`.
The shared `--format` flag selects `text`, `yaml`, or `json` for reports
submitted through the core reporter. When omitted, a report's text template
selects text; otherwise scalar values and nonempty string lists use text, while
structured values and empty collections use YAML. Explicit text without a
template uses YAML for structured values. Invalid or empty format values are
usage errors. Raw output, help, completion, and diagnostics are not encoded as
reports.
### Modes and visibility
Each invocation starts in ordinary mode. `--quiet`, `--verbose`, and `--debug`
@@ -154,9 +162,9 @@ example version --quiet
Reporting flags do not go before or between command-path components. Tokens
consumed as values and tokens after `--` retain their normal meaning.
The reserved long spellings are `--quiet`, `--verbose`, `--debug`, and
`--progress`; application declarations cannot reuse them. There are no built-in
short spellings. Applications may define aliases such as `-q → --quiet`,
The reserved long spellings are `--quiet`, `--verbose`, `--debug`,
`--progress`, and `--format`; application declarations cannot reuse them. There
are no built-in short spellings. Applications may define aliases such as `-q → --quiet`,
`-v → --verbose`, and `-d → --debug`; canonical and aliased occurrences share
the same ordering. Thus `example export --verbose -q` selects quiet mode.