Greeter: a single-command CLI

Copy Markdown View Source

A minimal complete example. One command, one required argument, three options (including a typed one with a validator and an env var fallback).

Full runnable project: examples/greeter/.

The command

defmodule Greeter.CLI do
  use Cheer.Command

  command "greeter" do
    about "Greet someone with style"
    version "1.0.0"

    argument :name, type: :string, required: true, help: "Who to greet"

    option :greeting, type: :string, default: "Hello", env: "GREETER_GREETING",
      help: "Greeting word"

    option :loud, type: :boolean, short: :l, help: "SHOUT the greeting"

    option :times, type: :integer, short: :n, default: 1,
      validate: fn n -> if n in 1..10, do: :ok, else: {:error, "times must be 1-10"} end,
      help: "Repeat the greeting"
  end

  @impl Cheer.Command
  def run(%{name: name} = args, _raw) do
    greeting = "#{args[:greeting]}, #{name}!"
    greeting = if args[:loud], do: String.upcase(greeting), else: greeting

    for _ <- 1..args[:times] do
      IO.puts(greeting)
    end

    :ok
  end

  def main(argv) do
    Cheer.run(__MODULE__, argv, prog: "greeter")
  end
end

Run it

cd examples/greeter
mix deps.get

mix run -e 'Greeter.CLI.main(["world"])'
# Hello, world!

mix run -e 'Greeter.CLI.main(["world", "--loud", "--times", "3"])'
# HELLO, WORLD!
# HELLO, WORLD!
# HELLO, WORLD!

GREETER_GREETING=Hey mix run -e 'Greeter.CLI.main(["Ada"])'
# Hey, Ada!

mix run -e 'Greeter.CLI.main(["world", "--times", "42"])'
# error: --times must be one of: ... (validator failure)

mix run -e 'Greeter.CLI.main(["--help"])'
# Usage: greeter <name> [OPTIONS]
# ...

Or build as a proper escript:

mix escript.build
./greeter world --loud --times 3

What it shows

  • Required positional -- argument :name, required: true with the missing-arg error path.
  • Typed option with validator -- :times is coerced to integer and range-checked.
  • Env var fallback -- GREETER_GREETING is consulted when --greeting is not passed.
  • Short alias -- -l for --loud, -n for --times.
  • Version flag -- version "1.0.0" wires up -V / --version.
  • Auto help -- -h / --help generated from the declaration.

See also