Router for Prompt

Simplifies defining commands, sub-commands and arguments.

Choose the module responsible for taking the command line arguments and use Prompt.Router, otp_app: :your_app at the top.

Then simply define your commands and arguments.

Exposes a main/1 function that is called with the command line args. It runs the matching command and halts the VM with the command's exit code.

Exposes a run/1 function that does the same but returns the exit code instead of halting, which is what you want in tests:

assert My.CLI.run(["checkout", "--branch", "dev"]) == 0

To have main/1 return the exit code too, for example when it is called from a release or a Mix task, use use Prompt.Router, otp_app: :my_app, halt: false.

Arguments

See arg/3

Help

help/0 prints, in order of priority, the help: option given to use Prompt.Router, this module's @moduledoc, or usage generated from the commands. command --help prints the command module's @moduledoc (when available) followed by generated usage. Override help/0 or command_help/1 to change this.

--help output goes to stdout and exits 0. When parsing fails, the reason and the generated usage of the command go to stderr and the exit code is 1.

Distributing as an escript

Escripts strip documentation chunks by default, so @moduledoc text is not available at runtime. Add strip_beams: [keep: ["Docs"]] to the escript: options in mix.exs if you want moduledoc text in help. It is needed only for that: generated usage and the help: option work without it.

Example

defmodule My.CLI do
  use Prompt.Router, otp_app: :my_app

  command :checkout, My.CheckoutCommand do
    arg :help, :boolean
    arg :branch, :string, short: :b, default: "main"
  end

  command "", My.DefaultCommand do
    arg :info, :boolean
  end
end

defmodule My.CheckoutCommand do
  use Prompt.Command

  @impl true
  def process(arguments) do
    # arguments will be a map of the defined arguments and their values
    # from the command line input
    # If someone used the command and passed `--branch  feature/test`, then
    # `argmuments would look like `%{help: false, branch: "feature/test"}`
    display("checking out " <> arguments.branch)
  end
end

defmodule My.DefaultCommand do
  use Prompt.Command

  @impl true
  def init(arguments) do
    # you can implement the `c:init/1` callback to transform
    # the arguments before `c:process/1` is called if you want
    arguments
  end
  
  @impl true
  def process(arguments) do
    # arguments will have a key of `:leftover` for anything
    # passed to the command that doesn't have a `arg` defined.
    # If someone called this with `--info --test something`, then
    # arguments will look like `%{info: true, leftover: ["something", "--test"]}`:
    # unused positional values first, then unknown flags as typed
    display("showing info")
  end
end