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).

Make subcommands optional so an unknown first token falls through to this command's own positional arguments.

Without this, a command that declares both arguments and subcommands treats an unrecognized first token as an unknown command and errors. With it, a token that does not match a declared subcommand is parsed as a positional argument and option parsing continues across it, so the parent command runs. Declared subcommands still take precedence: an exact (or, with infer_subcommands, an unambiguous prefix) match dispatches to the subcommand.

command "roba" do
  args_conflicts_with_subcommands(true)

  argument :prompt, type: :string, required: false
  subcommand Roba.Commands.History
end

roba history dispatches to the subcommand, while roba "summarize this" --model haiku runs the parent with prompt: "summarize this" and model: "haiku".

Declare a positional argument.

Arguments are matched in declaration order. Options:

• :type - :string (default), :integer, :float, or :boolean
• :required - true or false (default)
• :num_args - collect several positional tokens into a list: an integer for an exact count or a range (1..3) for a variable count. Consumption is greedy (up to the max), so a variadic argument should be declared last. Too few values is a usage error.
• :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 - true to hide from help output
• :deprecated - true for a bare marker, or a string reason; shown in help
• :display_order - integer controlling position in help (lower first)

• :validate - fn value -> :ok | {:error, msg} end

• :parse - fn value -> {:ok, parsed} | {:error, msg} end to transform the value into a domain type (runs after coercion, before :validate)

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
end

Mark this command as deprecated. Shows a (deprecated) marker in the parent's help and prints a warning to stderr when the command is used. Pass a string to include a reason (and a migration hint).

command "old-name" do
  deprecated "use `new-name` instead"
end

Set 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.

Allow this command to accept unknown subcommands (e.g. plugins on $PATH).

When enabled, any argv token that does not match a declared subcommand and is not an option is captured and surfaced to run/2 via args[:external_subcommand] as {name, rest_argv}. Declared subcommands still take precedence. Commands that opt in should generally not also declare positional arguments -- leftover positionals are routed to the external-sub capture, not to arguments.

Example: a git-style plugin dispatcher that execs git-<name> from $PATH.

command "git-like" do
  external_subcommands(true)

  # ... declared subs, options ...
end

def run(args, _raw) do
  case args[:external_subcommand] do
    {name, rest} -> System.cmd("git-#{name}", rest)
    nil -> :ok
  end
end

Define a named group of options with a constraint.

Supports:

• mutually_exclusive: true -- at most one option in the group can be set
• co_occurring: true -- all or none of the options must be set
• required: true -- at least one option in the group must be set

Constraints combine: mutually_exclusive: true, required: true means exactly one member must be set.

Hide this command from its parent's help, shell completion, and unknown-command listings. The command stays fully dispatchable; only its visibility is affected.

Useful for internal, experimental, or legacy commands.

command "debug" do
  hide true
end

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. :p for -p)
• :required - true or false (default)
• :default - default value when not provided (:count defaults to 0, :multi defaults to [])
• :default_missing_value - value used when the flag is present with no value (--color alone). Distinct from :default (flag absent). An explicit value must use the --flag=value form; --flag value leaves value as a positional.
• :multi - true to allow repeated flags collected into a list (e.g. --tag a --tag b)
• :num_args - collect several values from a single flag invocation into a list: an integer for an exact count (num_args: 2 accepts --point 1 2) or a range for a variable count (num_args: 1..3). Collection stops at the next flag or --. Distinct from :multi, which repeats the flag. An out-of-range count is a usage error. Negative numbers are always accepted as values (--range -5 5).
• :allow_hyphen_values - true to accept a value that starts with -, such as --pattern -v or --range -a -b (with num_args). Without it, only negative numbers are accepted as hyphen-leading values.
• :value_delimiter - split a single value on this string into a list, e.g. value_delimiter: "," makes --tags a,b,c yield ["a", "b", "c"]. Each element is coerced to :type and checked against :choices. Combines with :multi (each occurrence is split and the results flattened).

• :parse - fn value -> {:ok, parsed} | {:error, msg} end to transform the value into a domain type (an atom, a Date, a struct). Runs after :type coercion and :value_delimiter splitting, before :choices and :validate. For a list value (:multi, :num_args, :value_delimiter) it is applied to each element.

• :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 - true to hide from help output
• :deprecated - true for a bare marker, or a string reason; shown in help and warned to stderr when the option is used
• :global - true to 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_if_all - keyword list [other_opt: value]; required only when every pair matches
• :required_unless - atom or list of atoms; this option is required unless any of the named options are present
• :required_unless_all - list of atoms; required unless all 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 - true if 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.