Declarative, namespaced subcommand tools for JustBash.

JustBash.CLI turns a tree of subcommands — like acme pr review --report 1234 — into a single value you register in the :commands map. It handles routing, typed argument parsing, and auto-generated help and errors, so host applications stop hand-rolling case-statement routers and hand-maintained --help text.

A CLI is plain data: a %JustBash.CLI{} holding a tree of JustBash.CLI.Command nodes. Build it with new/2 and command/2, then register the struct directly:

alias JustBash.CLI

cli =
  CLI.new("acme", doc: "Acme operations toolkit", commands: [
    CLI.command("pr", doc: "Pull request management", commands: [
      CLI.command("review",
        doc: "Review a pull request",
        flags: [
          report:  [type: :integer, required: true, doc: "ID of the report to review"],
          format:  [type: :string, default: "text", values: ~w(text json), doc: "Output format"],
          verbose: [type: :boolean, short: "-v"]
        ],
        run: &Acme.PR.review/1)
    ])
  ])

bash = JustBash.new(commands: %{"acme" => cli})

Each leaf's :run is a one-argument handler that receives a JustBash.CLI.Invocation and returns {result, bash} — the same contract as a custom JustBash.Commands.Command:

def review(%JustBash.CLI.Invocation{flags: flags, bash: bash}) do
  report = MyApp.PullRequests.fetch!(flags.report, bash.context.user)
  {JustBash.Commands.Command.ok(render(report, flags.format)), bash}
end

Flags

Flag specs use the exact shape of JustBash.Commands.ArgParser: a keyword list of name: [type: ..., ...]. Supported keys: :type (:boolean, :string, :integer, :float, :accumulator), :short, :long (defaults to --name), :aliases, :default, :required, :values (enum), :transform, and :doc (used in help output).

Flag specs are validated at build time (command/2 raises ArgumentError):

• an unrecognized spec key is rejected — a typo'd or imagined key would otherwise be silently ignored and indistinguishable from a working one.
• --help/-h are reserved — see "Reserved flags" below.
• :required and :default are mutually exclusive (a required flag errors when omitted, so the default could never apply).
• a :default must be a member of :values when both are given (the enum check only runs on flags the user actually provides, so an out-of-range default would slip past it).
• an alias must start with --, and no two flags may share a long form, an alias, or a short form — the parser indexes them into one map, so a collision would silently bind the wrong flag.
• a long form or alias may not contain = — the parser splits --flag=value on the first = before matching, so such a spelling could never be reached.

Flag aliases

:aliases gives one flag extra long spellings, for renaming a flag without breaking callers: target_on: [type: :string, aliases: ["--target-date"]] accepts both --target-on and --target-date. :long stays canonical and is the only form shown in usage lines, help, and describe/1 — aliases are accepted, not advertised.

:values is compared against the coerced value, so list members must match the flag's :type — e.g. type: :integer, values: [1, 2] (integers, not ~w(1 2)). The raw :values list is also what describe/1 and the help text surface to agents.

Flag names are atoms, so a name that is an Elixir reserved word (e.g. end, fn, do) can't be written bare in the keyword list. Give it an explicit :long instead: end_date: [type: :string, long: "--end"].

Beyond required-ness, types, and :values, two hooks cover custom validation, both producing the same exit-2 + usage-line failure as a flag error:

• a flag's :transform may return {:error, message} for single-field checks (a numeric range, a parseable date);
• a command-level :validate callback runs after parsing for cross-field rules (start <= end). See command/2.

Passthrough flags

A leaf that wraps a backend whose flags aren't known at definition time can set allow_unknown_flags: true. Undeclared flags are then collected into Invocation.extra_flags as a raw token list (ready to forward verbatim) instead of erroring, while declared flags and positionals are parsed as usual. Put declared positionals before passthrough flags, and prefer --flag=value form for unambiguous forwarding. See command/2.

Authorization

To make a subtree present only for some callers — genuinely absent, not just hidden — there are two approaches:

• Build the tree from context (first-class). A %JustBash.CLI{} is plain data, so build it per session and conditionally append gated groups based on bash.context before registering it. Routing, help, and describe/1 all reflect exactly the tree you built. This is the most flexible path and the right one for fully dynamic trees.
• A :visible? predicate (declarative sugar). Attach visible?: fn bash -> ... end to a node; run/4 prunes nodes the predicate rejects before routing, so they're unroutable (reported as unknown commands) and omitted from help. Pass the same bash to describe/2/render_docs/2 to get the catalog as that caller sees it.

Reserved flags

--help and -h are reserved: the router intercepts them before a leaf ever parses, so a leaf can request help in one turn. A flag spec may not claim either form (including a flag named :help, whose derived long is --help) — command/2 raises if it does. Because interception happens first, --help/-h anywhere before a -- terminator wins even when it would otherwise be a flag's value (e.g. acme pr review --format -h shows help).

-- handling

A leading -- before a subcommand is consumed and routing continues (acme -- pr review reaches pr review), so wrappers that prepend -- still route. This is intentionally not POSIX -- semantics — -- only acts as an options/help terminator once routing reaches a leaf and hands the remaining tokens to the parser.

Positional arguments

Positionals are a flat list, so command/2 rejects ambiguous shapes at build time: a required positional may not follow an optional one, and a variadic must be last. A lone - (the stdin convention) is treated as a flag by the router and is not supported as a positional; pass it after -- if a leaf needs it as a literal value.

Trust model

CLI handlers are ordinary host Elixir code with the same trust model and crash isolation as any custom command — they are not sandboxed. A crashing handler is caught and turned into an error result, but it runs with full access to the host.