A simple declarative command line interface builder cli
1.1.1 Latest release released
30 2
Julien Reichardt


Build Status ISC

Command Line Interface for Crystal

A simple Command line interface builder which aims to be easy to use.


Add the dependency to your shard.yml:

    github: j8r/clicr


This library uses generics, thanks to Crystal's powerful type-inference, and few macros, to provide this following advantages:

  • Compile time validation - methods must accept all possible options and arguments
  • No possible double commands/options at compile-time
  • Declarative NamedTuple configuration
  • Customizable configuration - supports all languages (See parameters)
  • Fast execution, limited runtime


Simple example

require "clicr"
  label: "This is my app.",
  commands: {
    talk: {
      label:      "Talk",
      action:    {"CLI.say": "t"},
      arguments: %w(directory),
      options:   {
        name: {
          label:   "Your name",
          default: "foo",
        no_confirm: {
          short: 'y',
          label:  "Print the name",

module CLI
  def self.say(arguments, name, no_confirm)
    puts arguments, name, no_confirm

Example of commands:

$ myapp --help

Myapp can do everything

  t, talk   Talk

  --name=foo         Your name
  -y, --no-confirm   Print the name

'myapp --help' to show the help.
$ myapp talk /tmp name=bar
no, bar in /tmp
$ myapp talk home name=bar -y
yes, bar in home
$ myapp talk test
no, foo in test

Advanced example

See the one in the spec test

CLI Composition

It's also possible to merge several commands or options together.

other = {
  pp: {
    label: "It pp",
    action: "pp"
  label: "Test app",
  commands: {
    puts: {
      alias: 'p',
      label: "It puts",
      action: "puts",

Help output:

Usage: myapp COMMAND

Test app

  p, puts   It puts
  pp        It pp

'myapp --help' to show the help.



Example: s, start

commands: {
  short: {
    action: { "say": "s" },
    label: "Starts the server",
    description: <<-E.to_s,
    This is a full multi-line description
    explaining the command
  • action is a NamedTuple with as key the method to call, and as a value a command alia, which can be empty for none.
  • in action, parentheses can be added to determine the arguments placement, like
  • label is supposed to be short, one-line description
  • description can be a multi-line description of the command. If not set, label will be used.


Example: command FooBar, command mysource mytarget

arguments: %w(directory names)
arguments: {"source", "target"}
  • if a Tuple is given, the arguments number must be exactly the Tuple size.
  • if an Array is given, the arguments number must be at least, or more, the Array size


Boolean options

Example: -y, --no-confirm

options: {
  no_confirm: {
    short: 'y',
    label: "No confirmations",
  • short creates a short alias of one character - must be a Char
  • concatenating single characters arguments like -Ry1 is possible
  • dashes -, being invalid named arguments, will be replaced by _ when calling the action method.

Special case: the help_option, which is set to "help" with the options -h, --help by default, shows the help of the current (sub)command

String options

Example: --name=foo, or --name foo

options: {
  name: {
    label: "This is your name",
    default: "Foobar",
  • an optional default value can be set.
  • if a default is not set, a type can be defined to cast from a given type, instead of a raw String. For example, type: Int32 will call
  • can only be String (because arguments passed as ARGV are Array(String)) - if others type are needed, the cast must be done after the action method call


Copyright (c) 2020 Julien Reichardt - ISC License

  github: j8r/clicr
  version: ~> 1.1.1
License ISC
Crystal none


Dependencies 0

Development Dependencies 0

Dependents 2

Last synced .
search fire star recently