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 and mix

  ExCLI.DSL can generate a module compatible with escript.build as well as a mix 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 as app help command to show help about command.




• 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!