format_help(cmd) -> help

Generate markdown-formatted help text for a command

Returns a markdown string with the following sections:

1. # <command> — name heading
2. Summary and description (when set)
3. ## Usage — generated usage line
4. ## Options — pipe table with name, default, forms, and note columns
5. ## Arguments — pipe table with name, arity, default, and note columns
6. ## Subcommands — pipe table (when present)

Inline code spans carry semantic classes for themed rendering:

• type classes: .bool, .num, .str, .file, .dir
• role classes: .opt, .arg, .flag, .meta
• state classes: .req, .def, .multi, .neg

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

format_error(err) -> message

Format a parse error into a human-readable string

Formats the error table returned by cmd:parse() into a displayable string. Combines usage line, error message, and suggestions (when present). For err.kind == "help", returns the markdown help directly.