Crystal CLI

Yet another Crystal library for building command-line interface applications.

Installation

Add this to your application's shard.yml:

dependencies:
  cli:
    github: mosop/cli

Code Samples

Option Parser

class Command < Cli::Command
  class Options
    string "--hello"
  end

  def run
    puts "Hello, #{options.hello}!"
  end
end

Command.run %w(--hello world) # prints "Hello, world!"

Exit

class OpenIt < Cli::Command
  class Options
    arg "word"
  end

  def valid?
    args.word == "sesame"
  end

  def run
    if valid?
      exit! "Opened!"
    else
      error! "Not opened!"
    end
  end
end

OpenIt.run ARGV

Output:

$ open-it sesame
Opened!
$ echo $?
0
$ open-it paprika
Not opened!
$ echo $?
1

Subcommand

class Polygon < Cli::Supercommand
  command "triangle", default: true

  class Triangle < Cli::Command
    def run
      puts 3
    end
  end

  class Square < Cli::Command
    def run
      puts 4
    end
  end

  class Hexagon < Cli::Command
    def run
      puts 6
    end
  end
end

Polygon.run %w(triangle) # prints "3"
Polygon.run %w(square)   # prints "4"
Polygon.run %w(hexagon)  # prints "6"
Polygon.run %w()         # prints "3"

Aliasing

class Command < Cli::Supercommand
  command "l", aliased: "loooooooooong"

  class Loooooooooong < Cli::Command
    def run
      sleep 1000
    end
  end
end

Command.run %w(l) # sleeps

Inheritance

abstract class Role < Cli::Command
  class Options
    string "--name"
  end
end

class Chase < Cli::Supercommand
  class Mouse < Role
    def run
      puts "#{options.name} runs away."
    end
  end

  class Cat < Role
    def run
      puts "#{options.name} runs into a wall."
    end
  end
end

Chase.run %w(mouse --name Jerry) # prints "Jerry runs away."
Chase.run %w(cat --name Tom)     # prints "Tom runs into a wall."

Help

class Call < Cli::Command
  class Help
    header "Receives an ancient message."
    footer "(C) 20XX mosop"
  end

  class Options
    arg "message", desc: "your message to call them", required: true
    bool "-w", not: "-W", desc: "wait for response", default: true
    help
  end
end

Call.run %w(--help)
# call [OPTIONS] MESSAGE
#
# Receives an ancient message.
#
# Arguments:
#   MESSAGE (required)  your message to call them
#
# Options:
#   -w          wait for response
#               (default: true)
#   -W          disable -w
#   -h, --help  show this help
#
# (C) 20XX mosop

Versioning

class Command < Cli::Supercommand
  version "1.0.0"

  class Options
    version
  end
end

Command.run %w(-v) # prints 1.0.0

Shell Completion

class TicketToRide < Cli::Command
  class Options
    string "--by", any_of: %w(train plane taxi)
    arg "for", any_of: %w(kyoto kanazawa kamakura)
  end
end

puts TicketToRide.generate_bash_completion
# or
puts TicketToRide.generate_zsh_completion

Usage

require "cli"

and see:

• Code Samples
• Wiki
• API Document

Want to Do

• Application-Level Logger
• I18n

Release Notes

See Releases.