This README is the one indexed from the repository at its latest ref, not from the tag for this version.

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 Hello < Cli::Command
  class Options
    bool "--bye"
    arg "to"
  end

  def run
    if args.bye?
      print "Goodbye"
    else
      print "Hello"
    end
    puts " #{args.to}!"
  end
end

Hello.run %w(world) # prints "Hello, world!"
Hello.run %w(--bye world) # prints "Goodbye, world!"

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"

Replacing

class New < Cli::Command
  def run
    puts "new!"
  end
end

class Obsolete < Cli::Command
  replacer_command New
end

Obsolete.run # prints "new!"

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)

Output:

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.