Concepts

Copy Markdown View Source

A short vocabulary tour. Read once, then skim the guides.

Command

A module that use Cheer.Command and declares a command "<name>" do ... end block. Commands compose into trees of arbitrary depth.

defmodule MyApp.CLI.Deploy do
  use Cheer.Command

  command "deploy" do
    about "Deploy to an environment"
    # ... options, arguments, subcommands ...
  end

  @impl Cheer.Command
  def run(args, _raw), do: ...
end

Leaf commands (no subcommands) must implement run/2. Branch commands route argv to their children automatically.

Argument

A positional input. Matched by position, typed, optionally required.

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

Option

A flag. Long form (--port), optional short alias (-p), optional value, optional type. Boolean options automatically support --no-<name> negation.

option :port, type: :integer, short: :p, default: 4000, env: "PORT"
option :verbose, type: :boolean, short: :v

Cheer normalizes atom names to kebab-case in both the parser and help output, so :base_port becomes --base-port.

Subcommand

A nested command module registered under its parent:

command "devtool" do
  subcommand Devtool.Server   # devtool server ...
  subcommand Devtool.Db       # devtool db ...
end

Subcommand trees can nest arbitrarily deep.

Run

A leaf command's handler. Receives a parsed args map and the raw argv:

@impl Cheer.Command
def run(args, _raw_argv) do
  # args is already parsed, typed, validated
end

The args map contains parsed arguments and options by their declared name, plus any defaults and environment-variable fallbacks that applied. Unknown trailing tokens (after --) land in args[:rest] unless the command declares a named trailing_var_arg.

Help, usage, version

Every command gets -h / --help automatically. Commands that call version("1.0.0") also get -V / --version. Help output is derived from the metadata you declared, not from a parallel format file.

Metadata

Every command has a compile-time __cheer_meta__/0 function that returns the full declaration as a data structure. Cheer.tree/1 walks the tree and returns a nested map, useful for documentation, completion scripts, and testing.

Test runner

Cheer.Test.run/3 invokes a command in-process, captures stdout, and returns both the output and the handler's return value. No subprocess, no argv escaping. See Testing.