DEPRECATED

This library is no longer being maintained. It is being kept online to allow for past versions of the Amber CLI to still compile on pre Crystal 1.14 releases. Message Date: July 22nd 2025

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.