command_kit.rb

command_kit

• Homepage
• Forum | Issues
• Documentation

Description

A modular Ruby toolkit for building clean, correct, and robust CLI commands as plain-old Ruby classes.

Features

• Simple - Commands are plain-old ruby classes, with options and arguments declared as attributes. All features are Ruby modules that can be included into command classes.
• Correct - CommandKit behaves like a standard UNIX command.
  • Safely handles Ctrl^C / SIGINT interrupts and exits with 130.
  • Safely handles broken pipes (aka mycmd | head).
  • Respects common environment variables (ex: TERM=dumb and NO_COLOR).
  • Uses OptionParser for POSIX option parsing.
  • Disables ANSI color when output is redirected to a file or when NO_COLOR is set.
• Complete - Provides many additional CLI features.
  • OS detection.
  • Terminal size detection.
  • ANSI coloring support.
  • Interactive input.
  • Rich text printing support (fields, lists, and tables).
  • Subcommands (explicit or lazy-loaded) and command aliases.
  • Displaying man pages for --help/help.
  • Using the pager (aka less).
  • XDG directories (aka ~/.config/, ~/.local/share/, ~/.cache/).
  • Exception handling / Bug reporting.
• Testable - Since commands are plain-old Ruby classes, it's easy to initialize them and call #main or #run.

Anti-Features

• No additional runtime dependencies.
• Does not implement it's own option parser.
• Not named after a comic-book Superhero.

Requirements

• ruby >= 3.0.0

Install

$ gem install command_kit

gemspec

gem.add_dependency 'command_kit', '~> 0.3'

Gemfile

gem 'command_kit', '~> 0.3'

Examples

lib/foo/cli/my_cmd.rb

…

bin/my_cmd

#!/usr/bin/env ruby

$LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
require 'foo/cli/my_cmd'

Foo::CLI::MyCmd.start

--help

Usage: my_cmd [OPTIONS] [-o OUTPUT] FILE

Options:
    -c, --count INT                  Number of times (Default: 1)
    -o, --output FILE                Optional output file
    -v, --verbose                    Increase verbose level
    -h, --help                       Print help information

Arguments:
    FILE                             Input file

Examples:
    my_cmd -o path/to/output.txt path/to/input.txt
    my_cmd -v -c 2 -o path/to/output.txt path/to/input.txt

Example command

Testing

RSpec

…

Reference

• CommandKit::Arguments
• CommandKit::BugReport
• CommandKit::Colors
• CommandKit::Command
• CommandKit::CommandName
• CommandKit::Commands
  • CommandKit::Commands::AutoLoad
  • CommandKit::Commands::AutoRequire
• CommandKit::Completion::Install
• CommandKit::Description
• CommandKit::Edit
• CommandKit::Env
  • CommandKit::Env::Home
  • CommandKit::Env::Path
  • CommandKit::Env::Prefix
  • CommandKit::Env::Shell
• CommandKit::Examples
• CommandKit::ExceptionHandler
• CommandKit::FileUtils
• CommandKit::Help
  • CommandKit::Help::Man
• CommandKit::Interactive
• CommandKit::Main
• CommandKit::Open
• CommandKit::Options
  • CommandKit::Options::Quiet
  • CommandKit::Options::Verbose
• CommandKit::Pager
• CommandKit::Printing
  • CommandKit::Printing::Fields
  • CommandKit::Printing::Indent
  • CommandKit::Printing::Lists
  • CommandKit::Printing::Tables
• CommandKit::ProgramName
• CommandKit::Stdio
• CommandKit::Terminal
• CommandKit::Usage
• CommandKit::XDG

Real-World Examples

• configure_trusted_publisher
• ronin

Alternatives

• dry-cli
• cmdparse

Special Thanks

Special thanks to everyone who answered my questions and gave feedback on Twitter.

Copyright

Copyright (c) 2021-2025 Hal Brodigan

See {file:LICENSE.txt} for details.