Packages
A clap-inspired CLI framework for Elixir. Declarative command trees with typed options, validation, env var fallback, lifecycle hooks, param groups, shell completion, REPL mode, and in-process testing.
Current section
Files
Jump to
Current section
Files
docs/cookbook/script.md
# Script: a single-file CLI with Mix.install
A complete CLI in one executable `.exs` file. `Mix.install/2` declares the
dependencies at the top of the script, so there is no Mix project and no build
step: edit the file and run it.
## The script
`hexq` queries the hex.pm API. It uses [Req](https://hex.pm/packages/req) for
HTTP, which is the reason to reach for `Mix.install` over a plain `elixir`
script.
```elixir
#!/usr/bin/env elixir
Mix.install([
{:cheer, "~> 0.3"},
{:req, "~> 0.5"}
])
defmodule Hexq do
use Cheer.Command
command "hexq" do
about "Query hex.pm from a single-file script"
version "0.1.0"
subcommand_required true
subcommand Hexq.Info
subcommand Hexq.Versions
end
def get!(path), do: Req.get!("https://hex.pm/api/" <> path).body
end
defmodule Hexq.Info do
use Cheer.Command
command "info" do
about "Show a package's latest version and downloads"
argument :package, type: :string, required: true
end
@impl Cheer.Command
def run(%{package: name}, _raw) do
pkg = Hexq.get!("packages/#{name}")
IO.write("""
#{pkg["name"]} #{pkg["latest_stable_version"]}
downloads: #{pkg["downloads"]["all"]} all, #{pkg["downloads"]["recent"]} recent
""")
end
end
defmodule Hexq.Versions do
use Cheer.Command
command "versions" do
about "List a package's releases"
aliases ["v"]
argument :package, type: :string, required: true
option :limit, type: :integer, short: :n, default: 5, help: "How many to show"
end
@impl Cheer.Command
def run(args, _raw) do
"packages/#{args.package}"
|> Hexq.get!()
|> Map.fetch!("releases")
|> Enum.take(args.limit)
|> Enum.each(fn r -> IO.puts("#{r["version"]} #{String.slice(r["inserted_at"], 0, 10)}") end)
end
end
Cheer.main(Hexq, System.argv(), prog: "hexq")
```
The command modules are ordinary cheer commands; nothing about them is specific
to a script. The last line is the entry point. `Cheer.main/3` halts the VM with
exit code 0, or 2 on a usage error, as it does in an escript. `System.argv/0`
holds the arguments after the script name.
## Running it
```sh
chmod +x hexq.exs
./hexq.exs info cheer
./hexq.exs v cheer -n 3
./hexq.exs --help
```
The first run fetches and compiles the dependencies. Later runs reuse the
`Mix.install` cache, which is keyed on the dependency list and the Elixir and
OTP versions. Changing a dependency or upgrading Elixir compiles once more.
`MIX_INSTALL_DIR` moves the cache, and `Mix.install(deps, force: true)` rebuilds
it.
On an Apple Silicon Mac with Elixir 1.20 and OTP 29, `./hexq.exs --version`
took 3.7 to 4.4 seconds on the first run and about 0.4 to 0.5 seconds after
that, over a few runs. The same command as an escript took about 0.2 seconds.
## Formatting the script
`mix format` on a lone script has no Mix project to read cheer's exported
formatter settings from:
- With no `.formatter.exs`, it rewrites the DSL with parentheses
(`about("...")`). The code still works.
- `import_deps: [:cheer]` fails with `Unknown dependency :cheer given to
:import_deps`, because `import_deps` reads dependencies from a `mix.exs`.
To keep the DSL paren-free, put a `.formatter.exs` beside the script that
lists the macros it uses:
```elixir
[
inputs: ["*.exs"],
locals_without_parens: [
about: 1,
version: 1,
subcommand_required: 1,
subcommand: 1,
command: 2,
argument: 2,
option: 2,
aliases: 1
]
]
```
## Choosing a shape
| | Script (`Mix.install`) | Escript | Burrito binary |
|---|---|---|---|
| The user's machine needs | Elixir, and network access on the first run | Erlang/OTP | Nothing |
| Build step | None | `mix escript.build` | `mix release` per target |
| Startup | First run compiles; then the cost of starting Elixir | Starting the VM | Starting the VM; the first run also unpacks |
| Ships as | One source file | One file | One file per OS and architecture |
A script suits internal tools that change often and run where Elixir is
installed, and commands whose own work outlasts startup, such as calling a
remote API. An escript suits tools for machines with Erlang but not Elixir.
Burrito suits machines with neither.
## What it shows
- **`Mix.install/2`** -- dependencies declared in the script, cached between
runs.
- **A full command tree in one file** -- a root, two subcommands, an alias, a
typed option with a default, and `subcommand_required`.
- **`Cheer.main/3` as the last line** -- the same entry point and exit codes as
an escript.
## See also
- Cookbook: [Greeter](greeter.md) -- the same kind of CLI built as an escript.
- Cookbook: [Server](server.md) -- Burrito binaries and `Cheer.argv/0`.
- Guides: [Help and output](../guides/help_and_output.md).