CLI — Markdown View

Build command-line interfaces using typed spec definitions:

from cli.cli import run
from cli.model import CliArg, CliCommand, CliOption, CliSpec
import process

let args: List[CliArg] = [CliArg("name", True, False, "string")]
let opts: List[CliOption] = [CliOption("uppercase", "u", "Uppercase output", False, False, False, None, None, "string")]
let no_subs: List[CliCommand] = []
let no_aliases: List[Str] = []
let greet = CliCommand("greet", "Greet someone", None, no_aliases, args, opts, no_subs)

let cmds: List[CliCommand] = [greet]
let global: List[CliOption] = []
let examples: List[Str] = ["mytool greet Alice -u"]
let spec = CliSpec("mytool", "1.0.0", "A greeting tool", None, cmds, global, examples)

let m = run(spec, process.argv())

if m.command() == "greet" {
    mut msg = "Hello, " + m.arg("name") + "!"
    if m.flag("uppercase") {
        msg = msg.upper()
    }
    print(msg)
}

Define your CLI structure with CliSpec, CliCommand, CliArg, and CliOption data types, then use run() or parse() to process arguments.

Core functions

Function	Returns	Description
`run(spec, argv)`	`CliMatch`	Parse args, print errors and exit on failure
`parse(spec, argv)`	`Result[CliMatch, CliError]`	Parse args, return Result for manual error handling
`parse_env(spec, argv, env)`	`Result[CliMatch, CliError]`	Parse with env var fallback and defaults

CliMatch accessors

Method	Returns	Description
`m.command()`	`Str?`	Matched command name
`m.arg(name)`	`Str`	Get positional argument (raises if missing)
`m.opt(name)`	`Str?`	Get option value
`m.flag(name)`	`Bool`	Check if flag is set
`m.has(name)`	`Bool`	Check if any arg/opt/flag exists

Spec data types

CliSpec(name, version?, summary?, description?, commands, global_options, examples) - top-level CLI definition.

CliCommand(name, summary?, description?, aliases, args, options, subcommands) - a command or subcommand.

CliArg(name, required, repeated, parser) - a positional argument.

CliOption(long, short?, summary?, takes_value, required, repeated, default_value?, env_var?, parser) - a named option or flag. Set takes_value to True for options that accept a value, False for boolean flags.

Value parsers

Set the parser field on CliArg or CliOption to validate values automatically:

Parser	Description
`"string"`	Accept any string (default)
`parser_int()`	Parse integer
`parser_float()`	Parse float
`parser_bool()`	Parse boolean
`parser_one_of(["a", "b"])`	Restrict to allowed values
`parser_path_exists()`	Validate path exists
`parser_file_exists()`	Validate file exists
`parser_dir_exists()`	Validate directory exists

Built-in features

Feature	Behavior
`-h` / `--help`	Always recognized; prints structured help
`help <command>`	Shows command-specific help
Unknown commands/options	Shows "Did you mean ...?" suggestions
Error handling	Exits code 2 with location and suggestion

JSON and completion output

Function	Returns	Description
`render_json_error(err)`	`Str`	Stable JSON error for machine parsing
`render_json_help(spec, path)`	`Str`	Stable JSON help for automation
`completion(spec, shell)`	`Str`	Shell completion script (bash, zsh, fish)
`render_help(spec)`	`Str`	Formatted help text

Legacy API

The docopt-style parse_cli(spec_text) function is still available for simple use cases but the typed spec API above is preferred for new code.