Macros for declaring commands, arguments, options, subcommands, lifecycle hooks, param groups, and validation.
Summary
Functions
Set the command's description text, shown in help output.
Set text displayed after the auto-generated help.
Run a function on the result after run/2. Receives and returns result.
Set subcommand aliases (e.g. aliases ["co", "ck"] for checkout).
Declare a positional argument.
Set text displayed before the auto-generated help.
Run a function on args before run/2. Receives and returns args map.
Define a command block with the given name.
Set this command's display order as a subcommand in its parent's help output.
Define a named group of options with a constraint.
Allow matching subcommands from unambiguous name prefixes.
Set the command's extended description, shown by --help (long form).
Declare a named option (flag).
Like before_run, but inherited by all child subcommands.
Propagate this command's version to all subcommands.
Register a child subcommand module.
Require that a subcommand is provided (error instead of showing help).
Declare a named trailing variable argument.
Override the auto-generated usage line in help output.
Cross-parameter validation function. Receives args map, returns :ok or {:error, msg}.
Set the command's version string, printed by --version / -V.
Functions
Set the command's description text, shown in help output.
Set text displayed after the auto-generated help.
Run a function on the result after run/2. Receives and returns result.
Set subcommand aliases (e.g. aliases ["co", "ck"] for checkout).
Declare a positional argument.
Arguments are matched in declaration order. Options:
:type-:string(default),:integer,:float, or:boolean:required-trueorfalse(default):help- help text shown in--help:long_help- extended help text shown by--help(long form):value_name- placeholder name in help (e.g."FILE"):hide-trueto hide from help output:display_order- integer controlling position in help (lower first):validate-fn value -> :ok | {:error, msg} end
Set text displayed before the auto-generated help.
Run a function on args before run/2. Receives and returns args map.
Define a command block with the given name.
All DSL calls (about, argument, option, subcommand, etc.) go inside the block.
command "deploy" do
about "Deploy the app"
option :env, type: :string, required: true
endSet this command's display order as a subcommand in its parent's help output.
Lower numbers appear first. Commands without an explicit order fall back to declaration order in the parent.
Define a named group of options with a constraint.
Supports:
mutually_exclusive: true-- at most one option in the group can be setco_occurring: true-- all or none of the options must be set
Allow matching subcommands from unambiguous name prefixes.
When enabled, che will resolve to checkout if no other subcommand starts
with che. Ambiguous prefixes produce an error listing the candidates.
Exact matches always take precedence over prefix inference. Matching is
done against canonical names only -- aliases are not prefix-matched.
Set the command's extended description, shown by --help (long form).
Declare a named option (flag).
Options:
:type-:string(default),:integer,:float,:boolean, or:count:short- single-character alias atom (e.g.:pfor-p):required-trueorfalse(default):default- default value when not provided (:countdefaults to0,:multidefaults to[]):multi-trueto allow repeated flags collected into a list (e.g.--tag a --tag b):env- environment variable name to read as fallback:choices- list of allowed values:help- help text shown in--help:long_help- extended help text shown by--help(long form):value_name- placeholder name in help (e.g."FILE"):hide-trueto hide from help output:global-trueto propagate to all subcommands:aliases- list of alternative long names (e.g.[:colour]for:color):display_order- integer controlling position within its help section (lower first):help_heading- string; options sharing a heading are grouped under it in help:conflicts_with- atom or list of atoms; this option cannot be used with the named option(s):requires- atom or list of atoms; the named option(s) must also be present:required_if- keyword list[other_opt: value]; this option is required when any pair matches (i.e.args[other_opt] == value):required_unless- atom or list of atoms; this option is required unless any of the named options are present:validate-fn value -> :ok | {:error, msg} end
Boolean options automatically support --no-<name> negation (e.g. --no-color).
Extra positional arguments after -- are collected into args[:rest].
Like before_run, but inherited by all child subcommands.
Propagate this command's version to all subcommands.
Register a child subcommand module.
Require that a subcommand is provided (error instead of showing help).
Declare a named trailing variable argument.
Everything after the last declared positional (or after --) is collected
and available as args[name] instead of the default :rest key. The name
and help text are shown in the usage and help output.
Options:
:help- help text shown in--help:required-trueif at least one trailing arg must be provided
Override the auto-generated usage line in help output.
Cross-parameter validation function. Receives args map, returns :ok or {:error, msg}.
Set the command's version string, printed by --version / -V.