cli:cli

cli:cli@0.0.0

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

shellAdapter

One of pwsh, sh.

configurableGlobalArgs

FieldTypeRequiredDefaultDescription
manifestpathNoManifest file path
appConfigpathNoOverride the app config file to load for this invocation
verbosebooleanNofalseAdd 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
logModulePathsbooleanNofalseTag log entries with the Python module that wrote them instead of the repository's project name
logLevelenum one of debug, verbose, info, warn, errorNoLowest 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)
responseFormatenum one of plain-text, jsonNo"plain-text"Response output format (default: plain-text)
prettybooleanNofalseWhen used with --response-format json, pretty-print JSON output
complexInputFormatenum one of json, ymlNo"json"Input format for complex command arguments (default: json)
complexInputSourceTypeenum one of serialized, filepathNo"serialized"Source type for complex command arguments: serialized (inline) or filepath (default: serialized)

globalArgs

Extends configurableGlobalArgs.

FieldTypeRequiredDefaultDescription
manifestpathNoManifest file path
appConfigpathNoOverride the app config file to load for this invocation
verbosebooleanNofalseAdd 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
logModulePathsbooleanNofalseTag log entries with the Python module that wrote them instead of the repository's project name
logLevelenum one of debug, verbose, info, warn, errorNoLowest 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)
responseFormatenum one of plain-text, jsonNo"plain-text"Response output format (default: plain-text)
prettybooleanNofalseWhen used with --response-format json, pretty-print JSON output
complexInputFormatenum one of json, ymlNo"json"Input format for complex command arguments (default: json)
complexInputSourceTypeenum one of serialized, filepathNo"serialized"Source type for complex command arguments: serialized (inline) or filepath (default: serialized)
repoRootpathNoRepository root path (default: the current directory, searched upward for a manifest)
runtimeConfigpathNoOverride the runtime config file to load for this invocation
fromStdinbooleanNofalseTake this command's inputs, by name, from the envelope piped to stdin by a command run with --response-format json; a flag given beside it still wins, and a field the command declares no input for is refused. A document input given - takes the piped answer as that one input instead, and one given =-:<path> the field at that path, as =-:releases[0].notes

versionArgs

FieldTypeRequiredDefaultDescription
versionbooleanNofalsePrint the version of the application, or of the command it follows, and exit

environmentVariable

FieldTypeRequiredDefaultDescription
namestringYesThe variable's name, as it is set in the environment
helpstringYesWhat the variable means to somebody setting it, as the application's documentation prints it

featureFlag

FieldTypeRequiredDefaultDescription
namestringYesThe flag's name, as a configuration's features switches it and code asks whether it is on
helpstringYesWhat turning the flag on changes, to somebody deciding whether to, as the application's --help and its documentation print it
defaultbooleanYesWhether the flag is on where no configuration says. A new behaviour that would break a client is declared off, so a client meets it by turning it on
retiresversionNoThe version of the application the flag is to be gone by, written major.minor.patch: the old behaviour deleted, the declaration moved to retiredFeatures. Absent, the flag has no planned retirement, and the help and the documentation say so
commandslist[string]No[]The commands whose behaviour the flag changes, each as it is invoked (build, issue run). A flag naming only commands a client is not handed is left out wherever they are; absent, the flag belongs to the application as a whole

retiredFeatureFlag

FieldTypeRequiredDefaultDescription
namestringYesThe retired flag's name, as a configuration's features switched it
behaviourstringYesWhat the application does now that the flag is gone, completing the refusal "the feature flag '<name>' is gone, and ..." a configuration still switching it is given

cliAppConfig

FieldTypeRequiredDefaultDescription
schemaVersionversionYesThe 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
externalSchemaslist[externalSchemaSpec]NoThe 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
namestringYesThe 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
projectstringYesThe 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
manifestTypetypeNoThe 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
configTypetypeNoThe 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
configDirpathYesThe 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
manifestPathpathNo"manifest.yml"The manifest a command reads where --manifest names none, relative to the repository root (default: manifest.yml)
globalArgAliasesdict[string, string]No{}The alias this application spells a global argument with, keyed by the declared name
registryregistryDefinitionNoThe 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
defaultAppConfigdict[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
defaultCliConfigdict[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
repositoryConfigKeyslist[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
environmentlist[environmentVariable]No[]The environment variables this application reads, beside the framework's own
featureslist[featureFlag]No[]The feature flags a client switches in this application's configuration, under features. Declaring one needs a configType whose schema names it in configRoots, which is what gives the configuration the mapping
retiredFeatureslist[retiredFeatureFlag]No[]The feature flags this application has retired, each with what it does now. A configuration still switching one is refused with that account rather than as a name nobody declared; an entry may go at the next major version
descriptionstringNoOne line saying what the application does, printed at the head of its --help and carried into its index
sourcePathpathNoThe 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

FieldTypeRequiredDefaultDescription
coordinatecoordinateYesThe exported schema that defines the type, as <namespace>:<name>@<version>; with no version where the catalog generating the index held none to name
definitionstringYesThe definition within that schema

appIndexError

FieldTypeRequiredDefaultDescription
codestringYesThe code as the envelope's errors carry it
meaningstringYesWhat it means that a run answered with the code, as its declaration states it
remedystringYesWhat the person who hit the code does about it, as its declaration states it
inheritedFromfloatingCoordinateNoThe package whose errors document declares the code, as <namespace>:<module>, on a command's codes expanded from the sets it inherits; absent for a code the command's own config declares, and in an index's errorSets, where the set names its package once

appIndexErrorSet

FieldTypeRequiredDefaultDescription
coordinatefloatingCoordinateYesThe package whose errors document declares the codes, as <namespace>:<module>
errorslist[appIndexError]No[]The codes it declares that a command of this application answers from it

appIndexExitCode

FieldTypeRequiredDefaultDescription
codeintegerYesThe number a process running the application exits with, as the envelope's exitCode reports it
meaningstringYesWhat a run exiting with the number has done, as the framework declares it

appIndexExample

FieldTypeRequiredDefaultDescription
commandLinestringYesThe invocation as it is typed: the application's name, the groups and the command's name, then the arguments its config states. An example of a pipe's acting half is preceded by the command line it is piped from and |, so the line is the whole pipeline
descriptionstringYesWhat the invocation does, as the command's config states it
outputstringNoWhat the invocation prints, as the command's config states it; absent where it states none

refusedExample

FieldTypeRequiredDefaultDescription
commandstringYesThe command the example is of, as the application invokes it: its name, the groups and the command's name
configpathYesThe command config that declares the example
argumentsstringYesThe example's arguments, as the config states them
reasonstringYesWhy the parser refused them, in its own words where it gave any

appIndexCommand

FieldTypeRequiredDefaultDescription
namestringYesThe name the command is invoked by: the last word of its command line, after any group
helpstringNoThe command's help, as its config states it
audienceenum one of public, internalYesWho the command is released to: what it states, else what the nearest group above it states, else the application's
configpinnedCoordinateYesThe 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
errorslist[appIndexError]No[]The codes the command's own config declares. With those of each set inheritsErrors names, in its order and each code once, they are every code the command can answer with
inheritsErrorslist[floatingCoordinate]No[]The packages the command answers codes from beside its own, each an entry of the index's errorSets, in the order a code is answered by the first that declares it: those its config inherits, followed through what each inherits in turn, then the framework's
exampleslist[appIndexExample]No[]Worked invocations of the command, in the order its config states them, each written out whole

appIndexGroup

FieldTypeRequiredDefaultDescription
namestringYesThe name the group is invoked by, after the application's name or the group above it
helpstringNoThe group's help, as the registry that makes it a group states it; absent where it states none
audienceenum one of public, internalYesWho the group is released to: what its registry states, else what the nearest group above it states, else the application's
commandslist[appIndexCommand]No[]The commands invoked directly under this group
groupslist[appIndexGroup]No[]The groups nested directly under this one

appIndexGlobalArgs

FieldTypeRequiredDefaultDescription
typeslist[appIndexType]YesThe definitions that declare the arguments: globalArgs, and versionArgs for --version
aliasesdict[string, string]No{}The alias this application spells a global argument with, keyed by the declared name

appIndexConfigLayer

FieldTypeRequiredDefaultDescription
scopeenum one of checkout, user, repository, applicationYesWhich scope this is: one checkout's own file, the user's, the repository's, or what the application itself declares
appConfigstringNoThe 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
runtimeConfigstringNoThe file the runtime configuration is read from in this scope, on the same terms

cliAppIndex

FieldTypeRequiredDefaultDescription
schemaVersionversionYesThe 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
namestringYesThe application's name, as it is typed to run it
descriptionstringNoWhat the application does, as its declaration states it; absent where it states none
projectstringYesThe project the application is released with, as that project's manifest names itself
versionstringYesThe 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
audienceenum one of public, internalYesWho the application is released to, as the manifest module holding it states and internal where it states none
modulefloatingCoordinateNoThe manifest module that holds the application, as <namespace>:<module> with no version; absent where no module of its repository does
configDirpathYesThe directory, under a repository the application acts on, that its configuration is read from
manifestTypeappIndexTypeNoThe definition a repository's manifest is read as; absent for an application that reads no manifest
configTypeappIndexTypeNoThe definition the application's own configuration is written to; absent for an application that has none
globalArgsappIndexGlobalArgsYesThe arguments every command of the application takes, and the aliases this application spells them with
runtimeConfigTypeappIndexTypeYesThe definition a runtime configuration document, cli.config.yml, is written to
envelopeappIndexTypeYesThe definition every command answers in under --response-format json
configLayerslist[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
environmentlist[environmentVariable]No[]The environment variables the application reads: the framework's, then its own
featureslist[featureFlag]No[]The feature flags a client switches in the application's configuration, each with its help, its default and when it retires
errorSetslist[appIndexErrorSet]No[]The codes each package declares that the application's commands answer from it, each package once, which a command names in its inheritsErrors
exitCodeslist[appIndexExitCode]No[]The numbers a process running the application exits with, each with what it means, as the framework every command runs under declares them
commandslist[appIndexCommand]No[]The commands invoked with no group, directly after the application's name
groupslist[appIndexGroup]No[]The groups invoked directly after the application's name, each holding its commands and the groups under it

commandArgDefaults

FieldTypeRequiredDefaultDescription
namestringYesThe command these defaults apply to, by the name it is invoked by
argsdict[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

FieldTypeRequiredDefaultDescription
namestringYesThe group these defaults apply to, by the name it is invoked by under the group holding it
argsdict[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
commandslist[commandArgDefaults]No[]Defaults for single commands under this group, one entry per command
resourceslist[resourceArgDefaults]No[]Defaults for the commands under each group nested directly in this one, one entry per group. Each outranks this group's args

argDefaults

FieldTypeRequiredDefaultDescription
argsdict[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
commandslist[commandArgDefaults]No[]Defaults for single commands invoked with no group, one entry per command
resourceslist[resourceArgDefaults]No[]Defaults for the commands under each group invoked directly after the application's name, one entry per group. A group nested in another has its entry in that group's resources

cliRuntimeConfig

FieldTypeRequiredDefaultDescription
schemaVersionversionYesThe 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
argDefaultsargDefaultsNo{}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
shellAdaptershellAdapter one of pwsh, shNoThe shell adapter commands run through. Absent, the host shell is detected, the same as when no runtime config file exists.
enginestringNo"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)
appRootpathNo"."The directory <app> engine installs and pins Python in and syncs dependencies from, relative to the repository root unless absolute (default: .)

commandContextConfig

FieldTypeRequiredDefaultDescription
cliAppcliAppConfigYesThe application's declaration, as loaded
appConfigConfigTYesThe application's own configuration for the repository the command acts on, composed from every scope; absent for an application that declares no configType
cliRuntimecliRuntimeConfigYesThe runtime configuration the command runs under, composed from every scope

commandContext

FieldTypeRequiredDefaultDescription
manifestManifestTYesThe 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
repoRootpathYesThe 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
configcommandContextConfig[ManifestT, ConfigT]YesThe configuration the command runs under: the application's declaration, its own configuration and the runtime configuration
commandstringNo""The name the running command was invoked by
resourcestringNoThe group the command was invoked under, the nearest where groups nest; absent for a command with none

commandRunArgument

FieldTypeRequiredDefaultDescription
namestringYesThe argument's declared name, as the command's inputs or the global arguments spell it
valuestringNoWhat was given: a string as written, anything else as its JSON text. Absent where the value is withheld
withheldbooleanNofalseWhether 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

FieldTypeRequiredDefaultDescription
schemaVersionversionYesThe 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
uuidstringYesThis run's own identity, a uuid minted as it starts
parentstringNoThe 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
applicationstringYesThe application the command belongs to, by the name its declaration states
commandlist[string]YesThe command as it was invoked: its group where it has one, then its name
argumentslist[commandRunArgument]No[]The arguments the run was given, and none it left to a default
repoRootpathYesThe repository the run acted on
startedAtdatetimeYesWhen the run started
elapseddurationYesHow long the run took, from its start to its answer
exitCodeintegerYesThe exit code the run answered with
errorCodeslist[string]No[]The code of each error the run answered with, in order
pidintegerYesThe process the run ran in
inProcessbooleanNofalseWhether 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