Parsing rules

This page is the reference for what the parser accepts on the command line.

Order of input

listy add-items --list groceries egg milk -- --not-a-flag

Part	Read as
`add-items`	the subcommand
`--list groceries`	an option and its value
`egg milk`	typed arguments, then positionals
`--not-a-flag`	after `--`, so never treated as an option

Note

The subcommand, if any, must be the very first input. Everything after it is parsed against that subcommand's definition.

Options and arguments can be mixed freely after that.

Option values

--list groceries       # value as the next input
--list=groceries       # value after an equals sign
-n groceries           # short flag with a value

A value that starts with - has to use the = form. Otherwise the parser reads it as another flag:

--name=-weird          # name is "-weird"

Name conversion

Flags are matched against the option name and its aliases in any case style:

Flag	Matches
`--list-name`	`listName`, `ListName`, `list_name`, `LIST_NAME`
`-h`	`h`, `H`

Argument names are shown in kebab-case in help output. Set kebabCaseArgumentName: false in the help options to keep them as written.

Short flags

A single letter is a short flag: -v, -h, -i.

Short flags can be written together. -rf is read as -r -f. This applies to letters only, and never after --. It is mostly useful for boolean flags, since only the last flag in the group can take a value.

Short flags do not accept =value. Use the long form for that.

Boolean flags

--verbose              # true
--no-verbose           # false
--verbose=false        # false
--no-verbose=true      # false

Full details in Boolean flags.

Repeating an option

Options coerced to an array or a set can appear more than once, and the values are merged:

listy --items egg --items milk         # ["egg", "milk"]
listy --items egg,milk                 # ["egg", "milk"]

Repeating anything else is an error. See Repeatable options.

Dotted keys

Options coerced with coerce.object accept nested fields written as dotted flags, or a full JSON string:

listy --db.host=localhost --db.port 5432
listy --db '{"host":"localhost","port":5432}'

See Object options.

Ending option parsing

-- stops option parsing. Everything after it becomes a typed argument or a positional, even when it starts with a dash.

listy --name=-weird -- -file.txt --not-an-option
# name: "-weird"
# arguments and positionals: ["-file.txt", "--not-an-option"]

Passing a string instead of argv

run accepts a string and splits it the way a shell would, quotes included. This is convenient in tests:

cli.run("add-items --list groceries --items egg,milk");
cli.run(["add-items", "--list", "groceries"]);