Cli

The object you pass to defineCLI.

Property	Type	Description
`cliName`	`string`	The name of the program. Required.
`options?`	`Record<string, Option>`	Options keyed by name. The key must be a valid JavaScript identifier, so `inputDir` becomes `--input-dir`.
`arguments?`	`Record<string, Argument>`	Typed arguments, in the order they are read.
`allowPositionals?`	`boolean`	Collect leftover input as an untyped `string[]`. Typed arguments are filled first.
`subcommands?`	`Subcommand[]`	Subcommands built with `defineSubcommand`. Do not write the objects by hand.
`meta?`	`CliMeta`	Text used by help output and generated docs.

See Option, Argument, and Subcommand.

CliMeta

Property	Type	Description
`usage?`	`string`	Usage line, for example `listy <command> [options]`. Terminal help only.
`description?`	`string`	Plain text. Supports multiple lines and ANSI colors. Preferred in terminal help.
`descriptionMarkdown?`	`string`	Markdown. Preferred in generated Markdown, and formatted when printed to a terminal.
`example?`	`string`	Examples. Shown at the bottom of terminal help, inside a code block in Markdown.
`markdownTitle?`	`string`	Top heading of the generated Markdown. Defaults to `cliName`.

A CLI has no placeholder or hidden, unlike a subcommand.

Returned methods

defineCLI returns the definition with these attached.

run

(input: string | string[]) => { value } | { error }

Parses the input, runs the matching handlers, and returns the result. It splits a string the way a shell would. It does not catch handler errors.

runAsync

(input: string | string[]) => Promise<{ value } | { error }>

Same as run, but waits for every handler to settle.

execute

(input?: InferInputType) => void

Runs the command with already typed values instead of terminal input. Throws a CliError when the input is invalid or no handler is attached.

executeAsync

(input?: InferInputType) => Promise<void>

Same as execute, but waits for every handler to settle.

onExecute

(handler: (result: OutputType) => void | Promise<void>) => () => void

Adds a handler and returns an unsubscribe function that removes it. Handlers run only for the command that was actually called.

The result that a handler receives:

Field	Description
`subcommand`	The subcommand name, or `undefined` for the main CLI.
`options`	Validated option values.
`arguments`	Validated argument values.
`positionals`	Leftover input, when `allowPositionals` is true.
`context`	Where each value came from and its raw input.

See Context.

generateCliHelpMessage

(options?: PrintHelpOptions) => string

generateSubcommandHelpMessage

(subcommandName: string, options?: PrintHelpOptions) => string

The CLI attaches both on the first run or runAsync call, which is why they are optional in the type. Inside a handler they are always there. generateSubcommandHelpMessage throws DefinitionErrorCode.SubcommandHelpNotFound for a name that does not exist.

See Help message.

The parse result

{ value: { subcommand, options, arguments, positionals, context }, error: undefined }
{ value: undefined, error: CliError }

Check error first. See CliError.