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

Add configuration path discovery

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 04:44:01 +00:00
parent aeb70e5873
commit b38130548e
8 changed files with 307 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/cli.md
View File

@@ -421,21 +421,32 @@ for native evidence definitions.
### Explain a configuration path
`config explain --path POINTER` explains the effective and historical value at a
JSON Pointer path. `--path` is required; an explicitly empty value selects the
root. The default scope is `app`; `--format yaml` or `--format json` selects
JSON Pointer path. An explicitly empty path selects the root. `config explain
--list` discovers paths when the selected scope supports path discovery. An
invocation with neither mode displays help; the two modes cannot be combined.
The default scope is `app`; `--format yaml` or `--format json` selects
structured output, and automatic output uses text. `--scope all` is unsupported.
```text
example config explain --path /server/addr
example config explain --path /profiles/team~1summary --format yaml
example config explain --path= --format yaml
example config explain --list --under /profiles --historical
```
Listing normally includes current paths. `--historical` adds paths that only
occurred in history; `--under POINTER` selects a subtree, and `--explicit=true`
or `--explicit=false` filters current paths by native explicitness. Historical-only
paths do not match an explicitness filter. These options require `--list`.
The report contains the scope and each selected path's current presence and,
when present, its explicitness. Path discovery does not include values or history.
Pointer tokens use JSON Pointer escaping: `~1` represents `/` and `~0`
represents `~`. A malformed pointer is a usage error with status `2` and is
rejected before acquisition. A well-formed path that is unknown in the selected
configuration is an operational error with status `1`. Text output comes from
the scope's native explanation writer.
configuration is an operational error with status `1`. Text output includes
the scope's native explanation and available field metadata. Structured output
includes metadata when supplied by the scope.
Structured output uses these root fields: