SkillAgentSearch skills...

Clim

Slim command line interface builder for Crystal.

GenerateConvertImprove

Install / Use

/learn @at-grandpa/Clim
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

clim

"clim" is slim command line interface builder for Crystal.

"clim" = "cli" + "slim"

spec1 spec2 spec3 spec4 spec5 format-check completion

Goals

  • Slim implementation.
  • Intuitive code.

Support

  • [x] Option types
    • [x] Int8
    • [x] Int16
    • [x] Int32
    • [x] Int64
    • [x] UInt8
    • [x] UInt16
    • [x] UInt32
    • [x] UInt64
    • [x] Float32
    • [x] Float64
    • [x] String
    • [x] Bool
    • [x] Array(Int8)
    • [x] Array(Int16)
    • [x] Array(Int32)
    • [x] Array(Int64)
    • [x] Array(UInt8)
    • [x] Array(UInt16)
    • [x] Array(UInt32)
    • [x] Array(UInt64)
    • [x] Array(Float32)
    • [x] Array(Float64)
    • [x] Array(String)
  • [x] Argument types
    • [x] Int8
    • [x] Int16
    • [x] Int32
    • [x] Int64
    • [x] UInt8
    • [x] UInt16
    • [x] UInt32
    • [x] UInt64
    • [x] Float32
    • [x] Float64
    • [x] String
    • [x] Bool
  • [x] Default values for option & argument
  • [x] Required flag for option & argument
  • [x] Nested sub commands
  • [x] --help option
  • [x] Customizable help message
  • [x] version macro
  • [x] Command name alias
  • [x] Bash completion

Installation

Add this to your application's shard.yml:

dependencies:
  clim:
    github: at-grandpa/clim
    version: 0.17.1

Samples

Minimum sample

src/minimum.cr

require "clim"

class MyCli < Clim
  main do
    run do |opts, args|
      puts "#{args.all_args.join(", ")}!"
    end
  end
end

MyCli.start(ARGV)

$ crystal build -o ./minimum src/minimum.cr
$ ./minimum foo bar baz
foo, bar, baz!

Command information sample

src/hello.cr

require "clim"

module Hello
  class Cli < Clim
    main do
      desc "Hello CLI tool."
      usage "hello [options] [arguments] ..."
      version "Version 0.1.0"
      option "-g WORDS", "--greeting=WORDS", type: String, desc: "Words of greetings.", default: "Hello"
      argument "first_member", type: String, desc: "first member name.", default: "member1"
      argument "second_member", type: String, desc: "second member name.", default: "member2"
      run do |opts, args|
        print "#{opts.greeting}, "
        print "#{args.first_member} & #{args.second_member} !\n"
        print "And #{args.unknown_args.join(", ")} !"
        print "\n"
      end
    end
  end
end

Hello::Cli.start(ARGV)

$ crystal build src/hello.cr
$ ./hello --help

  Hello CLI tool.

  Usage:

    hello [options] [arguments] ...

  Options:

    -g WORDS, --greeting=WORDS       Words of greetings. [type:String] [default:"Hello"]
    --help                           Show this help.
    --version                        Show version.

  Arguments:

    01. first_member       first member name. [type:String] [default:"member1"]
    02. second_member      second member name. [type:String] [default:"member2"]

$ ./hello -g 'Good night' Ichiro Miko Takashi Taro
Good night, Ichiro & Miko !
And Takashi, Taro !

Sub commands sample

src/fake-crystal-command.cr

require "clim"

module FakeCrystalCommand
  class Cli < Clim
    main do
      desc "Fake Crystal command."
      usage "fcrystal [sub_command] [arguments]"
      run do |opts, args|
        puts opts.help_string # => help string.
      end
      sub "tool" do
        desc "run a tool"
        usage "fcrystal tool [tool] [arguments]"
        run do |opts, args|
          puts "Fake Crystal tool!!"
        end
        sub "format" do
          desc "format project, directories and/or files"
          usage "fcrystal tool format [options] [file or directory]"
          run do |opts, args|
            puts "Fake Crystal tool format!!"
          end
        end
      end
      sub "spec" do
        desc "build and run specs"
        usage "fcrystal spec [options] [files]"
        run do |opts, args|
          puts "Fake Crystal spec!!"
        end
      end
    end
  end
end

FakeCrystalCommand::Cli.start(ARGV)

Build and run.

$ crystal build -o ./fcrystal src/fake-crystal-command.cr
$ ./fcrystal

  Fake Crystal command.

  Usage:

    fcrystal [sub_command] [arguments]

  Options:

    --help                           Show this help.

  Sub Commands:

    tool   run a tool
    spec   build and run specs

Show sub command help.

$ ./fcrystal tool --help

  run a tool

  Usage:

    fcrystal tool [tool] [arguments]

  Options:

    --help                           Show this help.

  Sub Commands:

    format   format project, directories and/or files

Run sub sub command.

$ ./fcrystal tool format
Fake Crystal tool format!!

How to use

require & inherit

require "clim"

class MyCli < Clim

  # ...

end

Command Informations

desc

Description of the command. It is displayed in Help.

class MyCli < Clim
  main do
    desc "My Command Line Interface."
    run do |opts, args|
      # ...
    end
  end
end

usage

Usage of the command. It is displayed in Help.

class MyCli < Clim
  main do
    usage  "mycli [sub-command] [options] ..."
    run do |opts, args|
      # ...
    end
  end
end

alias_name

An alias for the command. It can be specified only for subcommand.

require "clim"

class MyCli < Clim
  main do
    run do |opts, args|
      # ...
    end
    sub "sub" do
      alias_name  "alias1", "alias2"
      run do |opts, args|
        puts "sub_command run!!"
      end
    end
  end
end

MyCli.start(ARGV)

$ ./mycli sub
sub_command run!!
$ ./mycli alias1
sub_command run!!
$ ./mycli alias2
sub_command run!!

version

You can specify the string to be displayed with --version.

require "clim"

class MyCli < Clim
  main do
    version "mycli version: 1.0.1"
    run do |opts, args|
      # ...
    end
  end
end

MyCli.start(ARGV)

$ ./mycli --version
mycli version: 1.0.1

If you want to display it even with -v, add short: "-v".

require "clim"

class MyCli < Clim
  main do
    version "mycli version: 1.0.1", short: "-v"
    run do |opts, args|
      # ...
    end
  end
end

MyCli.start(ARGV)

$ ./mycli --version
mycli version: 1.0.1
$ ./mycli -v
mycli version: 1.0.1

Short option for help

The short help option is not set by default. If you want help to appear by specifying -h , specify help short: "-h" .

(However, it should not conflict with other options.)

require "clim"

class MyCli < Clim
  main do
    desc "help directive test."
    usage "mycli [options] [arguments]"
    help short: "-h"
    run do |opts, args|
      # ...
    end
  end
end

MyCli.start(ARGV)

$ ./mycli -h

  help directive test.

  Usage:

    mycli [options] [arguments]

  Options:

    -h, --help                       Show this help.

$ ./mycli --help

  help directive test.

  Usage:

    mycli [options] [arguments]

  Options:

    -h, --help                       Show this help.

In addition to -h, you can specify any single character. For example, help short: "-a" .

option

You can specify multiple options for the command.

| Argument | Description | Example | Required | Default | | --------------- | ------------------ | ----------------------------- | -------- | ----------------------- | | First argument | short or long name | -t TIMES, --times TIMES | true | - | | Second argument | long name | --times TIMES | false | - | | type | option type | type: Array(Float32) | false | String | | desc | option description | desc: "option description." | false | "Option description." | | default | default value | default: [1.1_f32, 2.2_f32] | false | nil | | required | required flag | required: true | false | false |

class MyCli < Clim
  main do
    option "--greeting=WORDS", desc: "Words of greetings.", default: "Hello"
    option "-n NAME", "--name=NAME", type: Array(String), desc: "Target name.", default: ["Taro"]
    run do |opts, args|
      puts typeof(opts.greeting) # => String
      puts typeof(opts.name)     # => Array(String)
    end
  end
end

The type of the option is determined by the default and required patterns.

Number

For example Int8.

| default | required | Type | | --------- | ---------- | --------------------------------------- | | exist | true | Int8 (default: Your specified value.) | | exist | false | Int8 (default: Your specified value.) | | not exist | true | Int8 | | not exist | false | Int8 \| Nil |

String

| default | required | Type | | --------- | ---------- | ----------------------------------------- | | exist | true | String (default: Your specified value.) | | exist | false | String (default: Your specified value.) | | not exist | true | String | | not exist | false | String \| Nil |

Bool

| default | required | Type | | --------- | ---------- | -

at-grandpa

View profile

View on GitHub
GitHub Stars125
CategoryDevelopment
Updated3mo ago
Forks9
at-grandpa/clim

Languages

Crystal

Security Score

97/100

Audited on Dec 11, 2025

No findings