ExCLI
User friendly CLI apps for Elixir.
Screencast
Here is a small screencast of what a generated CLI app looks like.
Installation
Add ex_cli
to your list of dependencies in mix.exs
:
def deps do
[{:ex_cli, "~> 0.1.0"}]
end
Usage
The basic usage is to use ExCLI.DSL
to define your CLI, and ExCLI.run
to run it.
Here is a sample application:
defmodule MyApp.SampleCLI do
use ExCLI.DSL
name "mycli"
description "My CLI"
long_description ~s"""
This is my long description
"""
option :verbose, count: true, aliases: [:v]
command :hello do
aliases [:hi]
description "Greets the user"
long_description """
Gives a nice a warm greeting to whoever would listen
"""
argument :name
option :from, help: "the sender of hello"
run context do
if context.verbose > 0 do
IO.puts("Running hello command")
end
if from = context[:from] do
IO.write("#{from} says: ")
end
IO.puts("Hello #{context.name}!")
end
end
end
ExCLI.run!(MyApp.SampleCLI)
Which can be used in the following way.
sample_cli hello -vv world --from me
or using the command's alias:
sample_cli hi -vv world --from me
The application usage will be shown if the parsing fails. The above example would show:
usage: mycli [--verbose] <command> [<args>]
Commands
hello Greets the user
escript
and mix
integration
You can very easily generate a mix task or an escript using ExCLI
escript
Pass escript: true
to the use ExCLI.DSL
and set the module as escript
:main_module
:
# lib/my_escript_cli.ex
defmodule MyEscriptCLI do
use ExCLI.DSL, escript: true
end
# mix.exs
defmodule MyApp.Mixfile do
def project do
[app: :my_app,
escript: [main_module: MyEscriptCLI]]
end
end
mix
integration
Pass mix_task: TASK_NAME
to the use ExCLI.DSL
.
# lib/my_cli_task.ex
defmodule MyCLITask do
use ExCLI.DSL, mix_task: :great_task
end
You can then run
mix great_task
and get nicely formatted help with
mix help great_task
Documentation
Check out the documentation for more information.
Roadmap
-
Command parser
The command parser is now working and should be enough for a good number of tasks.
-
Integration with
escript
andmix
ExCLI.DSL
can generate a module compatible withescript.build
as well as amix
task. -
Usage generation
A nicely formatted usage is generated from the DSL.
-
Help command
Then the goal will be to add a
help
command which can be used asapp help command
to show help aboutcommand
. -
Command parser improvements
When the usage and help parts are done, there are a few improvements that will be nice to have in the command parser:
- the ability to set a default command
- the ability to easily delegate a command to another module
- command aliases
-
Man page generation
When all this is done, the last part will to generate documentation in man page and markdown formats, which will probably be done as a mix task.
Contributing
Contributions are very welcome, feel free to open an issue or a PR.
I am also looking for a better name, ideas are welcome!