cli:cli

`cli:cli@0.0.0`

A document is written as one of cliAppConfig, cliRuntimeConfig, cliAppIndex, commandRun.

`configurableGlobalArgs`

Field	Type	Required	Default	Description
`manifest`	`path`	No		Manifest file path
`appConfig`	`path`	No		Override the app config file to load for this invocation
`verbose`	`boolean`	No	`false`	Add detail to a command's human-readable output, such as all-clear lines and entries a report otherwise leaves out; it does not change the log level, which is --log-level
`logModulePaths`	`boolean`	No	`false`	Tag log entries with the Python module that wrote them instead of the repository's project name
`logLevel`	`enum` one of `debug`, `verbose`, `info`, `warn`, `error`	No		Lowest severity shown on the console, from the run's first line; the log file records every entry regardless. Outranks LOGGER_LEVEL when both are given. `verbose` shows each run's start and outcome (default: LOGGER_LEVEL, else the application's own)
`responseFormat`	`enum` one of `plain-text`, `json`	No	`"plain-text"`	Response output format (default: plain-text)
`pretty`	`boolean`	No	`false`	When used with --response-format json, pretty-print JSON output
`complexInputFormat`	`enum` one of `json`, `yml`	No	`"json"`	Input format for complex command arguments (default: json)
`complexInputSourceType`	`enum` one of `serialized`, `filepath`	No	`"serialized"`	Source type for complex command arguments: serialized (inline) or filepath (default: serialized)

`globalArgs`

Extends configurableGlobalArgs.

Field	Type	Required	Default	Description
`manifest`	`path`	No		Manifest file path
`appConfig`	`path`	No		Override the app config file to load for this invocation
`verbose`	`boolean`	No	`false`	Add detail to a command's human-readable output, such as all-clear lines and entries a report otherwise leaves out; it does not change the log level, which is --log-level
`logModulePaths`	`boolean`	No	`false`	Tag log entries with the Python module that wrote them instead of the repository's project name
`logLevel`	`enum` one of `debug`, `verbose`, `info`, `warn`, `error`	No		Lowest severity shown on the console, from the run's first line; the log file records every entry regardless. Outranks LOGGER_LEVEL when both are given. `verbose` shows each run's start and outcome (default: LOGGER_LEVEL, else the application's own)
`responseFormat`	`enum` one of `plain-text`, `json`	No	`"plain-text"`	Response output format (default: plain-text)
`pretty`	`boolean`	No	`false`	When used with --response-format json, pretty-print JSON output
`complexInputFormat`	`enum` one of `json`, `yml`	No	`"json"`	Input format for complex command arguments (default: json)
`complexInputSourceType`	`enum` one of `serialized`, `filepath`	No	`"serialized"`	Source type for complex command arguments: serialized (inline) or filepath (default: serialized)
`repoRoot`	`path`	No		Repository root path (default: the current directory, searched upward for a manifest)
`runtimeConfig`	`path`	No		Override the runtime config file to load for this invocation

`versionArgs`

Field	Type	Required	Default	Description
`version`	`boolean`	No	`false`	Print the version of the application, or of the command it follows, and exit

`environmentVariable`

Field	Type	Required	Default	Description
`name`	`string`	Yes		The variable's name, as it is set in the environment
`help`	`string`	Yes		What the variable means to somebody setting it, as the application's documentation prints it

`cliAppConfig`

Field	Type	Required	Default	Description
`schemaVersion`	`version`	Yes		The version of this document's schema that this document was written under -- granted by the meta-schema to every definition named in `metadata.documentRoots`, never declared
`externalSchemas`	`list[externalSchemaSpec]`	No		The schemas this declaration refers to, each under the alias its `name` gives. `manifestType` and `configType` resolve through an entry, which has to name an exported schema by `id`
`name`	`string`	Yes		The application's name: the program name its usage and `--help` print, the name its log file `logs/<name>.log` takes, and the name its index is registered under
`project`	`string`	Yes		The project this application is released with, as that project's `manifest.yml` names itself. The application's version is that manifest's `version`, and a nearest manifest stating another `project` is refused
`manifestType`	`type`	No		The definition a repository's manifest is loaded as, written `<alias>.<definition>` through an `externalSchemas` entry. Absent, the application reads no manifest: nothing is searched for and its commands are handed none
`configType`	`type`	No		The definition the application's own configuration is loaded as, written `<alias>.<definition>` through an `externalSchemas` entry. Absent, the application has no configuration: its commands are handed none and `config init` writes none
`configDir`	`path`	Yes		The directory the application's configuration files are kept in, relative to the root of the repository a command acts on, such as `.dev-tool`. The user's files are read from the same directory under their home; an absolute path names one place for every checkout and leaves no user scope
`manifestPath`	`path`	No	`"manifest.yml"`	The manifest a command reads where `--manifest` names none, relative to the repository root (default: `manifest.yml`)
`globalArgAliases`	`dict[string, string]`	No	`{}`	The alias this application spells a global argument with, keyed by the declared name
`registry`	`registryDefinition`	No		The application's command registries: `path` is their directory, relative to this declaration, and each entry of `registries` names a registry document under it. Absent, the application has only the commands every application carries
`defaultAppConfig`	`dict[string, any]`	No	`{}`	What the application's own configuration says where no file states a key: a layer under the repository's, the user's and the checkout's files, key by key, holding the values that differ from the config type's own defaults
`defaultCliConfig`	`dict[string, any]`	No	`{}`	What the runtime configuration, `cli.config.yml`, says where no file states a key: a layer under the repository's, the user's and the checkout's files, merged argument by argument within `argDefaults`
`repositoryConfigKeys`	`list[string]`	No	`[]`	The keys of the application's configuration that identify a repository and so may not be set in the user's file, which applies to every repository on the machine. One found there is refused by name
`environment`	`list[environmentVariable]`	No	`[]`	The environment variables this application reads, beside the framework's own
`description`	`string`	No		One line saying what the application does, printed at the head of its `--help` and carried into its index
`sourcePath`	`path`	No		The file this declaration was loaded from, set as it is loaded and written in no document. Relative registry paths are resolved against its directory, and the project's manifest is looked for at or above it

`appIndexType`

Field	Type	Required	Default	Description
`coordinate`	`string`	Yes		The exported schema that defines the type, as `<namespace>:<name>@<version>`; with no version where the catalog generating the index held none to name
`definition`	`string`	Yes		The definition within that schema

`appIndexCommand`

Field	Type	Required	Default	Description
`name`	`string`	Yes		The name the command is invoked by: the last word of its command line, after any group
`help`	`string`	No		The command's help, as its config states it
`audience`	`enum` one of `public`, `internal`	Yes		Who the command is released to: what it states, else what the nearest group above it states, else the application's
`config`	`string`	Yes		The coordinate the command's config is registered under in the same catalog, as `<namespace>:<app>.<command path>@<version>`; its input schema is held beside it

`appIndexGroup`

Field	Type	Required	Default	Description
`name`	`string`	Yes		The name the group is invoked by, after the application's name or the group above it
`help`	`string`	No		The group's help, as the registry that makes it a group states it; absent where it states none
`audience`	`enum` one of `public`, `internal`	Yes		Who the group is released to: what its registry states, else what the nearest group above it states, else the application's
`commands`	`list[appIndexCommand]`	No	`[]`	The commands invoked directly under this group
`groups`	`list[appIndexGroup]`	No	`[]`	The groups nested directly under this one

`appIndexGlobalArgs`

Field	Type	Required	Default	Description
`types`	`list[appIndexType]`	Yes		The definitions that declare the arguments: `globalArgs`, and `versionArgs` for `--version`
`aliases`	`dict[string, string]`	No	`{}`	The alias this application spells a global argument with, keyed by the declared name

`appIndexConfigLayer`

Field	Type	Required	Default	Description
`scope`	`enum` one of `checkout`, `user`, `repository`, `application`	Yes		Which scope this is: one checkout's own file, the user's, the repository's, or what the application itself declares
`appConfig`	`string`	No		The file the application's own configuration is read from in this scope: under the repository it acts on, or under the user's home where it begins `~/`. Absent for the application's scope, which is no file, and for an application with no configuration
`runtimeConfig`	`string`	No		The file the runtime configuration is read from in this scope, on the same terms

`cliAppIndex`

Field	Type	Required	Default	Description
`schemaVersion`	`version`	Yes		The version of this document's schema that this document was written under -- granted by the meta-schema to every definition named in `metadata.documentRoots`, never declared
`name`	`string`	Yes		The application's name, as it is typed to run it
`description`	`string`	No		What the application does, as its declaration states it; absent where it states none
`project`	`string`	Yes		The project the application is released with, as that project's manifest names itself
`version`	`string`	Yes		The version of the application this index describes, which is its project's: `major.minor.patch`, with the project's development marker where it carries one
`audience`	`enum` one of `public`, `internal`	Yes		Who the application is released to, as the manifest module holding it states and `internal` where it states none
`module`	`string`	No		The manifest module that holds the application, as `<namespace>:<module>` with no version; absent where no module of its repository does
`configDir`	`path`	Yes		The directory, under a repository the application acts on, that its configuration is read from
`manifestType`	`appIndexType`	No		The definition a repository's manifest is read as; absent for an application that reads no manifest
`configType`	`appIndexType`	No		The definition the application's own configuration is written to; absent for an application that has none
`globalArgs`	`appIndexGlobalArgs`	Yes		The arguments every command of the application takes, and the aliases this application spells them with
`runtimeConfigType`	`appIndexType`	Yes		The definition a runtime configuration document, `cli.config.yml`, is written to
`envelope`	`appIndexType`	Yes		The definition every command answers in under `--response-format json`
`configLayers`	`list[appIndexConfigLayer]`	No	`[]`	The scopes configuration is composed from, the one that wins first: each is laid over those after it, key by key. An argument given on the command line outranks them all, and a field's declared default answers where none states it
`environment`	`list[environmentVariable]`	No	`[]`	The environment variables the application reads: the framework's, then its own
`commands`	`list[appIndexCommand]`	No	`[]`	The commands invoked with no group, directly after the application's name
`groups`	`list[appIndexGroup]`	No	`[]`	The groups invoked directly after the application's name, each holding its commands and the groups under it

`commandArgDefaults`

Field	Type	Required	Default	Description
`name`	`string`	Yes		The command these defaults apply to, by the name it is invoked by
`args`	`dict[string, any]`	No	`{}`	What the command's arguments default to where the command line does not give them, keyed by each argument's declared name: one of the command's own inputs or a global argument. Outranks the `args` of the scopes above it

`resourceArgDefaults`

Field	Type	Required	Default	Description
`name`	`string`	Yes		The group these defaults apply to, by the name it is invoked by; for a command under nested groups, the group nearest the command
`args`	`dict[string, any]`	No	`{}`	What the arguments of every command under this group default to, keyed by each argument's declared name. Outranks the root `args`, and a `commands` entry here outranks it
`commands`	`list[commandArgDefaults]`	No	`[]`	Defaults for single commands under this group, one entry per command
`resources`	`list[resourceArgDefaults]`	No	`[]`	Entries for groups nested under this one. Composed across configuration scopes with the rest, but no command's defaults are read from one: a command's group is looked up among the root `resources` alone, by the name of the group nearest the command

`argDefaults`

Field	Type	Required	Default	Description
`args`	`dict[string, any]`	No	`{}`	What every command's arguments default to where the command line does not give them, keyed by each argument's declared name: a global argument, or an input of whichever command runs. `repoRoot` and `runtimeConfig` are refused here and at every scope below
`commands`	`list[commandArgDefaults]`	No	`[]`	Defaults for single commands invoked with no group, one entry per command
`resources`	`list[resourceArgDefaults]`	No	`[]`	Defaults for the commands under one group, one entry per group

`cliRuntimeConfig`

Field	Type	Required	Default	Description
`schemaVersion`	`version`	Yes		The version of this document's schema that this document was written under -- granted by the meta-schema to every definition named in `metadata.documentRoots`, never declared
`argDefaults`	`argDefaults`	No	`{}`	The standing values of command arguments: what each defaults to where the command line does not give it, for every command, for the commands under one group, or for one command. The nearest scope wins
`shellAdapter`	`enum` one of `pwsh`, `sh`	No		The shell adapter commands run through. Absent, the host shell is detected, the same as when no runtime config file exists.
`engine`	`string`	No	`"python3"`	The Python engine the application is configured for, as `python` and a version: `python3`, `python3.12`. `<app> engine` reports it, installs it where the Python it detects is older, and writes it under `--update` (default: `python3`)
`appRoot`	`path`	No	`"."`	The directory `<app> engine` installs and pins Python in and syncs dependencies from, relative to the repository root unless absolute (default: `.`)

`commandContextConfig`

Field	Type	Required	Default	Description
`cliApp`	`cliAppConfig`	Yes		The application's declaration, as loaded
`appConfig`	`ConfigT`	Yes		The application's own configuration for the repository the command acts on, composed from every scope; absent for an application that declares no `configType`
`cliRuntime`	`cliRuntimeConfig`	Yes		The runtime configuration the command runs under, composed from every scope

`commandContext`

Field	Type	Required	Default	Description
`manifest`	`ManifestT`	Yes		The manifest of the repository the command acts on; absent for an application that reads none, and for a command declaring `manifestOptional` where no manifest file is found
`repoRoot`	`path`	Yes		The root of the repository the command acts on: the one `--repo-root` names, else the directory holding the manifest found by searching upward from the current directory
`config`	`commandContextConfig[ManifestT, ConfigT]`	Yes		The configuration the command runs under: the application's declaration, its own configuration and the runtime configuration
`command`	`string`	No	`""`	The name the running command was invoked by
`resource`	`string`	No		The group the command was invoked under, the nearest where groups nest; absent for a command with none

`commandRunArgument`

Field	Type	Required	Default	Description
`name`	`string`	Yes		The argument's declared name, as the command's inputs or the global arguments spell it
`value`	`string`	No		What was given: a string as written, anything else as its JSON text. Absent where the value is withheld
`withheld`	`boolean`	No	`false`	Whether the value was left out of the record: a document handed as an input, or an argument declared sensitive. The name alone says the argument was given

`commandRun`

Field	Type	Required	Default	Description
`schemaVersion`	`version`	Yes		The version of this document's schema that this document was written under -- granted by the meta-schema to every definition named in `metadata.documentRoots`, never declared
`uuid`	`string`	Yes		This run's own identity, a uuid minted as it starts
`parent`	`string`	No		The `uuid` of the run that called this one, in the same process or in the process that started this one. Absent for a run nothing watched started
`application`	`string`	Yes		The application the command belongs to, by the name its declaration states
`command`	`list[string]`	Yes		The command as it was invoked: its group where it has one, then its name
`arguments`	`list[commandRunArgument]`	No	`[]`	The arguments the run was given, and none it left to a default
`repoRoot`	`path`	Yes		The repository the run acted on
`startedAt`	`datetime`	Yes		When the run started
`elapsed`	`duration`	Yes		How long the run took, from its start to its answer
`exitCode`	`integer`	Yes		The exit code the run answered with
`errorCodes`	`list[string]`	No	`[]`	The code of each error the run answered with, in order
`pid`	`integer`	Yes		The process the run ran in
`inProcess`	`boolean`	No	`false`	Whether the run was a call through the application's API, inside the process of whatever called it, and not a command line of its own