abstract class Admiral::Command

Initializes a command with a String, which will be split into arguments.

Initializes a command with an Array(String) of arguments.

Initializes a command with an Admiral::ArgumentList.

Returns the commands Arguments object.

You can access names arguments by name. You can also access the remaning arguments using .arguments[index].

Puts to the command's error IO.

Returns the commands Flags object.

You can access names flags by name.

Gets from the command's input IO.

Returns the parent command if one is specified, or returns an error.

Prints to the command's output IO.

Prints to the command's error IO.

Returns the commands program name.

Puts to the command's output IO.

The run command.

Invokes a sub command by name, passing self as the parent.

Defines a named command line argument.

Simple Arguments

Simple arguments are denoted only by a name and will compile to returning a String | Nil.

# hello.cr
class Hello < Admiral::Command
  define_argument planet

  def run
    puts "Hello #{arguments.planet || "World"}"
  end
end

HelloWorld.run

$ crystal build ./world.cr
$ ./hello
Hello World
$ ./hello Alderaan
Hello Alderaan

Typed Arguments

Arguments can also be assigned a type. This will result in a properly typed value when calling arguments.arg_name. By default arguments are not required and will return a Union including the type and Nil.

# hello_world.cr
class HelloWorld < Admiral::Command
  define_argument number_of_greetings : UInt32, default: 1_u32

  def run
    arguments.number_of_greetings.times do
      puts "Hello World"
    end
  end
end

HelloWorld.run

$ crystal build ./hello_world.cr
$ ./hello_world  3
Hello World
Hello World
Hello World

Built in argument types

The following classes are assignable as arguments by default:

• String
• Bool
• Float32
• Float64
• Int8
• Int16
• Int32
• Int64
• UInt8
• UInt16
• UInt32
• UInt64

Pro Tip: To make any Class or Struct assignable as a argument, define a .new(value : ::Admiral::StringValue) or #initialize(value : ::Admiral::StringValue).

Additional Argument Options

# hello_world.cr
class HelloWorld < Admiral::Command
  define_argument number_of_greetings : UInt32,
    description: "The number of times to greet the world", # The description of the argument to be used in auto generated help.
    default: 1_u32,                                        # The default value of the argument.
    required: true                                         # Denotes if a argument is required. Required arguments without a default value will raise an error when not specified at command invocation.

  def run
    arguments.number_of_greetings.times do
      puts "Hello World"
    end
  end
end

HelloWorld.run

Note: Required arguments cannot be defined after optional arguments.

Defines a command line flag.

Note: When defining flags, the underscore method name will translate to a hyphen on the command line. This can be overridden with the long: my_name option when defining the flag.

Simple Flags

Simple flags are denoted only by a name and will compile to returning a String | Nil.

# hello_world.cr
class HelloWorld < Admiral::Command
  define_flag planet

  def run
    puts "Hello #{flags.planet || "World"}"
  end
end

HelloWorld.run

$ crystal build ./hello_world.cr
$ ./hello_world
Hello World
$ ./hello_world --planet Alderaan
Hello Alderaan

Typed Flags

Flags can also be assigned a type. This will result in a properly typed value when calling flags.flag_name. By default flags are not required and will return a Union including the type and Nil.

# hello_world.cr
class HelloWorld < Admiral::Command
  define_flag number_of_greetings : UInt32, default: 1_u32, long: times

  def run
    flags.times.times do
      puts "Hello World"
    end
  end
end

HelloWorld.run

$ crystal build ./hello_world.cr
$ ./hello_world  --times 3
Hello World
Hello World
Hello World

Built in flag types

The following classes are assignable as flags by default:

• String
• Bool
• Float32
• Float64
• Int8
• Int16
• Int32
• Int64
• UInt8
• UInt16
• UInt32
• UInt64

Pro Tip: To make any Class or Struct assignable as a flag, define a .new(value : ::Admiral::StringValue) or #initialize(value : ::Admiral::StringValue).

Enumerable Flags

Enumerable flags allow for multiple values to be passed on the command line. For example with a defined flag with Array(String) would return an array of String values when calling the flag.

# hello_world.cr
class HelloWorld < Admiral::Command
  define_flag citizens : Array(String), long: citizen

  def run
    flags.citizen.each do |citizen|
      puts "Hello #{citizen}, citizen of Earth!"
    end
  end
end

HelloWorld.run

$ crystal build ./hello_world.cr
$ ./hello_world  --citizen Jim --citizen Harry
Hello Jim, citizen of Earth!
Hello Harry, citizen of Earth!

Additional Flag Options

# hello_world.cr
class HelloWorld < Admiral::Command
  define_flag number_of_greetings : UInt32,
    description: "The number of times to greet the world", # The description of the flag to be used in auto generated help.
    default: 1_u32,                                        # The default value of the flag.
    long: times,                                           # The long version of the flag ex: `long: times` for `--times`.
    short: t,                                              # The short version of the flag ex: `short: t` for `-t`.
    required: true                                         # Denotes if a flag is required. Required flags without a default value will raise an error when not specified at command invocation.

  def run
    flags.number_of_greetings.times do
      puts "Hello World"
    end
  end
end

HelloWorld.run

Adds a help to the command.

# hello.cr
class Hello < Admiral::Command
  define_help description: "A command that says hello"
  define_argument planet, default: "World"

  def run
    puts "Hello #{arguments.planet}"
  end
end

$ crystal build ./hello.cr
$ ./hello --help
Usage:
  ./hello [flags...] <planet> [arg...]

A command that says hello

Flags:
  --help

Arguments:
  planet (default: World)

Custom Help

You can also generate your own custom help text.

# hello.cr
class Hello < Admiral::Command
  define_help custom: "This is the help for my command"

  def run
  end
end

Registers a subcommand.

# hello.cr
class Hello < Admiral::Command
  class Planetary < Admiral::Command
    def run
      puts "Hello World"
    end
  end

  class Municipality < Admiral::Command
    def run
      puts "Hello Denver"
    end
  end

  register_subcommand planet : Planetary
  register_subcommand city : Municipality

  def run
    puts help
  end
end

HelloWorld.run

$ crystal build ./hello.cr
$ ./hello planet
Hello World
$ ./hello city
Hello Denver