Jacob logo

Jacob is a Command line application framework with built-in support for shell autocompletion and help. It even has some UI tools.

He’s going to help you build self contained escript CLI’s that can run on the BEAM.

Hello world

Create a new module in your application and use Jacob.Command in it.

defmodule Hello do
  use Jacob.Command

  @name "hello"
  @desc "say hello"

  def run(["hello", name]) do
    IO.puts("hello #{name}")
  end
end

build your escript with mix escript.build.

If your application is named myapp by default the escript filename will be myapp so you should be able to run your new hello command like that:

./myapp hello world

You can find more information about escripts with this command mix help escript.build

Built-in commands

By default Jacob ships with two built-in commands.

help

The help command can be used to display a listing of all the available commands in your application alongside their description.

shell:install-extension

where shell_name is either bash or zsh

This command can be used to install Jacob’s shell extension which will then enable tab completion on your application. For this extension to work your application’s escript file has to be in your system’s PATH.

Need more informations ? The doc is available on here: https://hexdocs.pm/jacob/

Installation

To use Jacob in your project, first add Jacob as a dependency:

def deps do
  [
    {:jacob, "~> 0.1.0"}
  ]
end

Then run mix deps.get and add Jacob’s main module to your project’s configuration.

def project do
  [
      escript: [main_module: Jacob.Main]
  ]
end

Configuration

Thereafter you’ll have to set some configuration in your config/config.exs file. The following are the defaults but you can ajust them as you like.

config :jacob, :command_sources, [Mix.Project.config()[:app]]
config :jacob, :console_name, Mix.Project.config()[:app]
config :jacob, :console_version, Mix.Project.config()[:version]
config :jacob, :escript_name, Mix.Project.config()[:escript][:name] || Mix.Project.config()[:app]

What’s this and why do i need it ?

It appears that mix dependencies cannot access the root configuration of a mix project. Therefore Jacob has to ask you for some of your project’s information, that is:

  • :command_sources

    In which applications does Jacob have to look in order to find your Jacob commands ? This is usally the name of your application.

  • :console_name

    What’s your console name ? We’ll default to the name of your application. This information is will then be show by the help command.

  • :console_version

    What’s your console version ? We’ll default to the version of your application. This information is will then be show by the help command.

  • :escript_name

    What’s the generated escript filename. This option will not rename the generated escript file name, but make Jacob aware of your escript filename.