argparser.command

argparser

command(name, opts) -> cmd

Create a new command parser with options, arguments, and subcommands

Returns a command object with chainable builder methods:

cmd:summary(text) — set one-line summary
cmd:description(text) — set longer description
cmd:option(name, spec) — add a named option (see option spec below)
cmd:argument(name, spec) — add a positional argument (see argument spec below)
cmd:command(name, spec) — add a subcommand (spec is a function or table with summary/description)
cmd:build() — finalize configuration
cmd:parse(argv) — parse an argument list

The opts table accepts default_subcommand (string) and subcommand_required (boolean, defaults to true).

Option spec

Fields for the spec table passed to cmd:option(name, spec):

short — one-char short alias (e.g. "v" for -v)
long — explicit long name (default: name with _ → -)
type or kind — "boolean", "string", "number", "file", "dir" (aliases: "bool", "str", "num")
default — default value
required — require option presence (default: false)
repeatable — collect repeated values into an array (default: false)
negatable — allow/disallow auto --no-<long> for bools (default: true)
choices — allowed values list
metavar — help placeholder for the value
note or help — help text

Argument spec

Fields for the spec table passed to cmd:argument(name, spec):

type or kind — same type system as options
nargs — one of "1", "?", "*", "+" (default: "1")
default — default when omitted
required — explicit requirement (inferred from nargs when not set)
note or help — help text

Parse return

On success, cmd:parse(argv) returns (parsed, nil) where parsed is a table keyed by option/argument names. When subcommands are used, parsed also contains subcommand (name) and args (sub-parsed table).

On failure or help, returns (nil, err) where err is a table:

kind — "help" or "parse_error"
code — stable error code: help, unknown_option, missing_value, invalid_value, invalid_negation, missing_option, missing_argument, invalid_argument, unknown_subcommand, missing_subcommand
message — human-readable message
usage — generated usage string
suggestions — optional list of Levenshtein-based alternatives