commandkit/docs/cli.md

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:

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:

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:

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.

Configuration scopes

An application installs one configuration suite with RegisterConfig. Its config scopes command lists scope names and the configuration operations currently installed for those scopes:

example config scopes
example config scopes --format yaml

Text output uses one scope: operation, operation line per scope. YAML uses a scopes sequence with explicit name and operations fields. Scope order is app, then promptkit, then other names alphabetically. A metadata-only scope can be listed without an acquisition callback. Discovery does not construct a runtime context or acquire configuration. It reports the intersection between declared scope capabilities and installed handlers, so an operation is listed only when the corresponding command is available.

Validate configuration

config validate loads and validates the selected scope. The default scope is app; --scope all validates every registered scope and is available when each scope declares validation. The command checks all selected capabilities before calling scope providers. Its default format is text; --format yaml emits a scopes sequence with name and valid: true for each scope that completed successfully.

example config validate
example config validate --scope promptkit --format yaml
example config validate --scope all

Each successful scope is reported as SCOPE: valid. Aggregate validation stops at the first load or output failure; records from earlier successful scopes may already have been written. Provider warnings go to the diagnostic stream and do not alone make validation fail. --config and --overlay preserve whether an empty value was explicitly supplied, so a scope callback can map those inputs to its own ConfigKit load policy. Help and invalid syntax do not call scope providers.

Show effective configuration

config show writes the provider's native effective YAML for one scope. Its default scope is app; --format yaml is accepted and YAML is the only initial format. Single-scope output is passed through unchanged, without a CommandKit header or document marker.

example config show
example config show --scope promptkit
example config show --scope all

--scope all acquires every selected scope and checks each effective writer before writing output. It then emits one YAML document per scope in discovery order, with a # scope: NAME comment after each document marker. Existing native markers and leading comments are retained; documents without a marker receive one. Scope labels containing line control characters are quoted to keep them on one comment line. A provider failure leaves the output stream empty. A rendering or output failure may leave an aggregate prefix, and the outcome reports incomplete report delivery.

List configuration sources

config sources reports the source inventory captured during the selected scope's acquisition. It reads the source facet once and does not reload configuration. The default scope is app; --scope all is unsupported. Text is the default format, and --format yaml returns a structured report:

scope: app
sources:
  - id: source-1
    label: "application config"
    path: /etc/example/config.yml
    layer: base
    kind: file
    underlay_index: 0
    imported_from: null

Each source includes id, label, path, layer, kind, underlay_index, and imported_from. The import location is null when absent; otherwise it has source_id, line, and column. Owning values and source order are preserved, including empty fields, zero coordinates, and synthetic sources without paths. An empty inventory is sources: []. Text output begins with the scope heading and then prints the same source fields, quoting labels and paths.

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.