Cheer

A clap-inspired CLI framework for Elixir. Define your command tree once and get parsing, validation, help, shell completion, a REPL, and in-process testing for free.

30-second taste

defmodule MyApp.CLI.Greet do
  use Cheer.Command

  command "greet" do
    about "Greet someone"

    argument :name, type: :string, required: true, help: "Who to greet"
    option :loud, type: :boolean, short: :l, help: "SHOUT"
  end

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

Cheer.run(MyApp.CLI.Greet, ["world", "--loud"], prog: "greet")
# "HELLO, WORLD!"

Features

• Declarative macro DSL for commands, options, arguments, and subcommands
• Typed options and arguments with automatic coercion
• Per-param and cross-param validation, choices, conditional-required
• Per-option relations (:conflicts_with, :requires) and param groups
• Env var fallback, defaults, boolean negation (--no-*)
• Auto-generated help with headings, display order, before/after text
• Subcommand prefix inference and "Did you mean?" suggestions
• External subcommands for git-style plugin dispatchers
• Shell completion for bash, zsh, fish, and PowerShell
• REPL mode driven by the same command tree
• In-process test runner with output capture
• Command tree introspection (Cheer.tree/1) for docs and scripts
• Zero runtime dependencies

Install

def deps do
  [{:cheer, "~> 0.1"}]
end

Documentation

Full docs on hexdocs.pm/cheer:

• Getting started -- install and a five-minute tour.
• Concepts -- vocabulary and mental model.
• Guides:Options, Arguments, Subcommands, Validation, Constraints, Help and output, Lifecycle hooks, Shell completion, REPL, Testing.
• Cookbook:Greeter (single command), Devtool (nested subcommands with hooks and groups).

Runnable examples

Standalone Mix projects that match the cookbook entries live under examples/:

• examples/greeter/ -- minimal single-command CLI.
• examples/devtool/ -- nested multi-command CLI with lifecycle hooks and groups.

cd examples/greeter && mix deps.get
mix run -e 'Greeter.CLI.main(["world", "--loud", "--times", "3"])'

License

MIT