Interface: ArgSchema

An argument schema definition for command-line argument parsing.

This schema is similar to the schema of Node.js util.parseArgs but with extended features:

• Additional required, description, and hidden properties
• Extended type support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
• Simplified default property (single type, not union types)

Signature

export interface ArgSchema

Properties

Name	Type	Description
choices (optional)	string[] | readonly string[]	Array of allowed string values for enum-type arguments. Required when type: 'enum', unless the argument has a parse function: if choices is missing or not an array, resolveArgs and parse() throw a TypeError, whether or not the argument is given. With a parse function and no choices, the value is passed to the function as for a string argument with a parse function. The argument value must be one of these choices, otherwise the error is an ArgResolveError with type 'type' and the code err:arg:invalid-choice (ArgsValidationErrorKeys.invalidChoice). The value is checked before parse is called, so a parse function receives only one of these choices and can change it, for example to upper case. Supports both mutable arrays and readonly arrays for type safety.
conflicts (optional)	string | string[]	Names of other options that conflict with this option. When this option is used together with any of the conflicting options, the error is an ArgResolveError with type 'conflict' and the code err:arg:conflict (ArgsValidationErrorKeys.conflict). Its values has the displayName and name of the argument whose conflicts names the other one, and the conflictDisplayName and conflictName of the other one. displayName and conflictDisplayName show an option as it was written, such as '-p', and name and conflictName are the schema keys. When both name each other, name is the one that comes first in the schema. A positional argument can be on either side, such as [file] and --stdin. It conflicts when it is given, and it is shown by its name, such as 'file' (in kebab-case with toKebab), as in its other errors. The message starts with the kind of the argument given as name: Positional argument 'file' conflicts with '--stdin' or Optional argument '--stdin' conflicts with 'file'. Conflicts only need to be defined on one side - if option A defines a conflict with option B, the conflict is automatically detected when both are used, regardless of whether B also defines a conflict with A. Supports both single option name or array of option names. Option names must match the property keys in the schema object exactly (no automatic conversion between camelCase and kebab-case).
default (optional)	string | boolean | number	Default value used when the argument is not provided. An option that is given without a value, or with a value that is rejected, also gets its default, along with the error. The type must match the argument's type property: - string type: string default - boolean type: boolean default - number type: number default - enum type: one of the choices values, or a value that a parse of your own returns - positional/custom type: string, boolean, or number default The default is used as is and never goes through parse, including when an option is given without a value. An explicit empty value, such as --name= or -n '', is a value, not a missing one: a string option without parse gets '' instead of the default, unless it is required. What parse returns is a value too, even undefined or null, and the default does not replace it. The value of a multiple argument is an array, so its default becomes the only element of the array: default: 'latest' gives ['latest']. The default of an enum option with choices is checked when it would be used, that is, when no value from the command line is used: one that is not one of the choices is reported as an ArgResolveError with type 'type' and the code err:arg:invalid-default (ArgsValidationErrorKeys.invalidDefault), and is not used. With a parse function of your own, or a map() transform, the default is a value that the function returns, which need not be one of the choices, and it is not checked. choice() returns the value as is, so its default is checked. For positional arguments, multiple ones included, the default is used when no value is left for the argument: when the positional values run out, or when the remaining ones are preserved for later required positional arguments. With required: true, the default is not used, and the argument is reported as required instead.
description (optional)	string	Human-readable description of the argument's purpose. Used for help text generation and documentation. Should be concise but descriptive enough to understand the argument's role.
hidden (optional)	boolean	Hide the argument from generated help or usage output. This is metadata for renderers. It does not affect parsing, validation, required checks, defaults, conflicts, or resolved values.
metavar (optional)	string	Display name hint for help text generation. Provides a meaningful type hint for the argument value in help output. Particularly useful for type: 'custom' arguments where the type name would otherwise be unhelpful. For a custom option that is given without a value, it is also the expected in the values of the err:arg:missing-value error (ArgsValidationErrorKeys.missingValue), which is 'custom' without it.
multiple (optional)	true	Allows the argument to accept multiple values. When true, the resolved value becomes an array. When the argument is not given and has no default, its value is undefined, not an empty array. For options: can be specified multiple times (--tags foo --tags bar) For positional: collects remaining positional arguments after preserving values for later required positional arguments. Note: Only true is allowed (not false) to make intent explicit.
negatable (optional)	boolean	Enables negation for boolean arguments using --no- prefix. When true, allows users to explicitly set the boolean to false using --no-option-name. When false or omitted, only positive form is available. Only applicable to type: 'boolean' arguments. The negated name is always no- followed by the full option name. An option named no-cache is negated by --no-no-cache, and --no-cache sets it to true. The negated form does not take a value. --no-flag=<value> is reported as err:arg:unexpected-value (ArgsValidationErrorKeys.unexpectedValue).
parse (optional)	(value: string) => any	Custom parsing function, used in place of the parsing of the argument's type. Required when type: 'custom': if it is missing or not a function, resolveArgs and parse() throw a TypeError, whether or not the argument is given. The function receives the raw string value and must return the parsed result. It should throw an Error (or subclass) if parsing fails. The function's return type becomes the resolved argument type. parse is called synchronously, and what it returns becomes the value, even undefined or null, so throw to reject a value. An async function returns a promise, and the promise becomes the value as is: it is not awaited, and its rejection is not reported as an error. Await the value, or each of its elements with multiple (for example with Promise.all()), and handle the rejection yourself: a rejection that nothing handles is an unhandled rejection, which ends a Node.js process by default. A boolean option calls parse with 'true', or 'false' for the negated form. Other options call it only with a value from the command line: when the option is given without a value, parse is not called and the missing value is reported as err:arg:missing-value (ArgsValidationErrorKeys.missingValue). When that error may suggest the argument after the option as its value, such as --port=-5 for --port -5, a parse function of your own is not called to check it either: only the parse functions of string(), number(), integer(), float() and choice(), which have no side effects, are called for that. An explicit empty value, such as --name= or -n=, is passed as '' unless required: true is set. An enum option with choices calls it only with one of them. Any other value, an explicit empty one included, is reported as err:arg:invalid-choice (ArgsValidationErrorKeys.invalidChoice), except that a required option reports an explicit empty value as required.
required (optional)	boolean	Marks the argument as required. When true, the argument must be provided by the user. If it is missing, the error is an ArgResolveError with type 'required' and the code err:arg:required-option (ArgsValidationErrorKeys.requiredOption), or err:arg:required-positional (ArgsValidationErrorKeys.requiredPositional) for a positional argument. Its values has the displayName as in the message, such as '--name' for an option ('--name' or '-n' with the short name n) and 'file' for a positional argument, and the name, which is the schema key. An option that is given without a value is reported as err:arg:missing-value (ArgsValidationErrorKeys.missingValue) instead, because the option itself was given. An explicit empty value, such as --name= or -n '', is still reported as required, but the option counts as given: it is true in explicit and takes part in conflicts, as any other given option does. For single-value positional arguments, omitting required keeps the argument required for compatibility, unless it has a default, which makes it optional. A multiple positional argument is optional unless required: true is set. Set required: false to make a positional argument explicitly optional. Optional positional arguments leave enough input values for later required positional arguments before consuming a value. In the type of the values, such as ArgValues, a single-value positional argument whose required may be false, such as one of type boolean, is optional, as it may be missing, unless it has a default. An optional required of type boolean, as declared here, says nothing, and keeps it required. TypeScript widens a required: true to boolean in a schema written apart from the call, such as { type: 'positional' as const, required: true }, which types the argument as optional: write such a schema as const.
short (optional)	string	Single character alias for the long option name. As example, allows users to use -x instead of --extended-option. Only valid for non-positional argument types.
toKebab (optional)	true	Converts the argument name from camelCase to kebab-case for CLI usage. When true, a property like maxCount becomes available as --max-count. This allows CAC user-friendly property names while maintaining CLI conventions. The toKebab option of resolveArgs and parse() applies it to all arguments, as in resolveArgs(args, tokens, { toKebab: true }). Note: Only true is allowed (not false) to make intent explicit.
type	"string" | "boolean" | "number" | "enum" | "positional" | "custom"	Type of the argument value. - 'string': Text value - 'boolean': true/false flag (can be negatable with --no- prefix). --flag=true and --flag=false set the value explicitly; any other value after = is a type error - 'number': Numeric value (parsed as integer or float) - 'enum': One of predefined string values (requires choices property, unless the argument has a parse function) - 'positional': Non-option argument by position - 'custom': Custom parsing with user-defined parse function Any other type, or no type, is a mistake that only untyped code can make: if the argument has no parse function, resolveArgs and parse() throw an Error, whether or not the argument is given.

parse Parameters

Name	Type	Description
value	string	Raw string value from command line

parse Returns

any — Parsed value of any type

parse Throws

• Error — Error or subclass when value is invalid

Examples

Basic string argument:

const schema: ArgSchema = {
  type: 'string',
  description: 'Server hostname',
  default: 'localhost'
}

Required number argument with alias:

const schema: ArgSchema = {
  type: 'number',
  short: 'p',
  description: 'Port number to listen on',
  required: true
}

Enum argument with choices:

const schema: ArgSchema = {
  type: 'enum',
  choices: ['info', 'warn', 'error'],
  description: 'Logging level',
  default: 'info'
}