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
• Repeated (:multi), multi-value (:num_args), delimited (:value_delimiter), and hyphen-leading (:allow_hyphen_values) option values
• Custom value parsers (:parse) that transform input into domain types
• Per-param and cross-param validation, choices, conditional-required
• Per-option relations (:conflicts_with, :requires) and param groups
• Env var fallback, defaults (including :default_missing_value), boolean negation (--no-*)
• Deprecation markers (deprecated) for options, arguments, and subcommands
• Auto-generated help with headings, display order, before/after text, hidden items (hide), terminal-width wrapping, and color (respecting NO_COLOR)
• Prefix inference and "Did you mean?" suggestions for mistyped commands and flags
• Optional subcommands (:args_conflicts_with_subcommands) and external subcommands for git-style plugin dispatchers
• Escript, Mix task (Cheer.MixTask), and long-running server entry points (Cheer.parse/3, Cheer.argv/0)
• 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) and markdown reference generation (Cheer.Reference)
• Zero runtime dependencies

Install

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

To keep the DSL paren-free under mix format, import cheer's formatter settings in your .formatter.exs:

[
  import_deps: [:cheer],
  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
]

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), Mix task (drive a mix task with a command), Server (argv configures a supervision tree).

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.
• examples/mix_task/ -- a Cheer command driving a mix task.
• examples/server/ -- argv parsed in Application.start/2 to configure a supervision tree.

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

License

MIT