Errors

Everything the parser reports is a CliError. run and runAsync return it in result.error. execute and executeAsync throw it.

CliError

Property	Type	Description
`message`	`string`	Written for the end user. Safe to print as is.
`cause`	`ErrorCause`	Which stage produced it.
`code`	error code	The specific problem.
`context`	object	Details, typed per code.

Narrowing on code narrows context with it.

import { CliError, ErrorCause, ValidationErrorCode } from "@staticbolt/args-parser";

Input goes through four stages, and cause says which one failed.

Cause	Stage	Codes
`Definition`	The CLI or subcommand definition is invalid.	`DefinitionErrorCode`
`Parse`	Terminal input could not be matched to the definition.	`ParseErrorCode`
`Validation`	A schema or a constraint rejected the input.	`ValidationErrorCode`
`Internal`	Something went wrong inside the library.	`InternalErrorCode`

Your CLI is wrong, not the user's input. The parser reports it the first time you run the CLI.

Code	Meaning
`MissingDefinitionName`	A CLI has no `cliName`, or a subcommand has no `name`.
`MissingOnExecute`	The command has no handler attached.
`MissingSchema`	An option or argument has no schema.
`EmptyDefinitionGroup`	`options`, `arguments`, or `subcommands` is present but empty.
`InvalidDefinitionOptionName`	An option or alias is written in negated form, such as `noFoo`.
`DuplicateDefinitionName`	Two options, arguments, aliases, or subcommands share a name.
`InvalidDefinitionArgumentName`	An argument name is numeric.
`InvalidOptionalArgumentDefinition`	An optional argument is not last, or is used with positionals.
`EmptyStringAliasName`	An alias is an empty string.
`SelfRequire`	A definition lists itself in `requires`.
`UnknownRequireName`	A name in `requires` does not exist.
`SelfConflict`	A definition lists itself in `conflictWith`.
`UnknownConflictName`	A name in `conflictWith` does not exist.
`DefinitionRequiresConflictOverlap`	The same name is in both `requires` and `conflictWith`.
`SubcommandHelpNotFound`	Help was asked for a subcommand that does not exist.

The input could not be read.

Code	Meaning
`UnknownSubcommand`	The first input matched no subcommand.
`CommandWithoutOptions`	An option was passed to a command that defines none.
`UnknownOption`	The flag is not defined.
`InvalidNegationForNonBooleanOption`	`--no-` was used on an option that is not a boolean flag.
`InvalidKeysForNonObjectOption`	Dotted keys were used on an option that is not an object option.
`PositionalArgumentNotAllowed`	Extra input, but positionals are not allowed.
`MissingRequiredOption`	A required option was not provided.
`MissingRequiredArgument`	A required typed argument was not provided.
`OptionMissingValue`	An option that needs a value was given none.
`FlagAssignedValue`	A short flag was given a value with `=`, which is not allowed.

The input was read, but rejected.

Code	Meaning
`SchemaValidationFailed`	The schema rejected the value. `context.issues` has the detail.
`CoercionFailed`	The coerce function could not convert the input.
`MutuallyExclusiveConflict`	An `exclusive` or `conflictWith` rule was broken.
`RequiredDependencyMissing`	Something listed in `requires` was not provided.
`OptionNotRepeatable`	An option that is not an array or a set was passed more than once.
`AsyncSchemaNotSupported`	The schema only validates asynchronously.
`NoOptionsToValidate`	Options were passed to a command that defines none.
`NoArgumentsToValidate`	Arguments were passed to a command that defines none.
`UnknownOptionValidation`	An option that does not exist was passed programmatically.
`UnknownArgumentValidation`	An argument that does not exist was passed programmatically.

Not caused by your definition or the user's input. Worth reporting as a bug.

Code	Meaning
`MissingPreparedTypes`	An internal type was not set up.
`CannotFindCliDefinition`	Subcommand resolution returned nothing.

See Errors for how to handle them.