The command_line_boss gem

command_line_boss makes it easy to build, test, and maintain complex command line interfaces. It is built on top of Ruby's OptionParser class and works best for traditional options-based command-line interfaces that you would build with OptionParser.

To use command_line_boss you are expected to already know how to define options with OptionParser.

For defining command-line interfaces with multiple commands and subcommands (aka a git-like interface), we recommend using a gem like thor. Other good alternatives also exist.

• Installation
• Usage
  • Getting started
  • Design your command line
  • Start your command line parser class
  • Define options
  • Define additional validations
  • Process any remaining non-option arguments
  • Optional: define help output
  • Use the parser
  • Run the command line
• Development
• Contributing
  • Commit message guidelines
  • Pull request guidelines
• License
• Code of Conduct

Installation

To install this gem, add to the following line to your application's gemspec OR Gemfile:

gemspec:

  spec.add_development_dependency "command_line_boss", '~> 0.1'

Gemfile:

gem "command_line_boss", "~> 0.1", groups: [:development, :test]

and then run bundle install.

If bundler is not being used to manage dependencies, install the gem by executing:

gem install command_line_boss

Usage

More detailed examples are given in the examples directory.

• examples/readme_example - a super-simple example of using this gem. The remainder of this section is a walkthrough of this example was constructed.
• examples/create_spreadsheet - a more complicated example complete with tests.

This section provides a step-by-step guide to building a super simple command line using this gem. A parser this simple would probably be easier to implement with OptionParser directly without this gem. This example is meant to show how you can get started.

This gem really starts to shine as your command-line interface grows beyond something this simple.

Getting started

The end result of this guide can be found in this project in the file examples/readme_example/create-spreadsheet.

Find a suitable directory to create your code in. For this example, all the code will live in ONE script file that you create and set its executable permission bit via chmod.

Make sure you have the command_line_boss gem installed.

Design your command line

Design the command line following the Google developer documentation style guide for command line syntax.

Here is what a simple example might look like that creates a spreadsheet with named sheets:

Usage:
create_spreadsheet SPREADSHEET_NAME --sheet=SHEET_NAME [--sheet=SHEET_NAME ...]

Start your command line parser class

The first step will be to create your own command line parsing class. This class must inherit from CommandLineBoss.

Add the attributess representing the items you want to capture from the command line. Set default values for these attributes in a method called set_defaults.

#!/usr/bin/env ruby

require 'command_line_boss'

class CreateSpreadsheetCli < CommandLineBoss
  attr_reader :spreadsheet_name, :sheet_names

  private

  def set_defaults
      @spreadsheet_name = nil
      @sheet_names = []
  end
end

Define options

Define private methods whose names follow the pattern define_*_option. Methods MUST be private or they won't be called.

Report any errors by calling add_error_message with the text of the error message.

The return value of these methods is ignored.

Continuing the example, add the following code to the CreateSpreadsheetCli class:

class CreateSpreadsheetCli < CommandLineBoss
  # ...

  private

  def define_sheet_option
    parser.on('--sheet=SHEET_NAME', 'Name of a sheet to create') do |name|
      add_error_message('Sheet names must be unique!') if sheet_names.include?(name)
      sheet_names << name
    end
  end
end

Define additional validations

Define private methods whose names follow the pattern validate_*. Methods MUST be private or they won't be called.

Report any errors by calling add_error_message with the text of the error message.

The return value of these methods is ignored.

Continuing the example, add the following code to the CreateSpreadsheetCli class:

class CreateSpreadsheetCli < CommandLineBoss
  # ...

  private

  def validate_spreadsheet_name_given
    add_error_message('A spreadsheet name is required') if spreadsheet_name.nil?
  end

  def validate_at_least_one_sheet_name_given
    add_error_message('At least one sheet name is required') if sheet_names.empty?
  end
end

Process any remaining non-option arguments

Implement parse_arguments to deal the remaining non-option arguments from the command line. Within this method, the args method returns the remaining non-option arguments.

For example, in the command line create-spreadsheet "Yearly Sales" --sheet Summary, args would return an array ['Yearly Sales'].

Remove any values from args that will be used. By default, if args is not empty after parse_arguments returns, an error will result.

Report any errors by calling add_error_message with the text of the error message.

The return value of this method is ignored.

Continuing the example, add the following code to the CreateSpreadsheetCli class:

class CreateSpreadsheetCli < CommandLineBoss
  # ...

  private

  def parse_arguments
    @spreadsheet_name = args.shift
  end
end

Optional: define help output

Include the CommandLineBoss::HelpOption module add a help option (-h and --help) and structure the help output.

Help output is divided into sections that is output as follows:

BANNER
HEADER
OPTIONS
FOOTER

The OPTIONS section is generated by OptionsParser.

You may provide the content for the other sections by implementing any or all of the methods: banner, header, and footer. These methods are expected to return a string with the content.

If you do not provide content for the banner section, it is generated by OptionsParser. The default banner looks something like this:

Usage: create-spreadsheet [options]

If you do not provide content for the header or footer sections, they are omitted from the help output.

Continuing the example, add the following code to the CreateSpreadsheetCli class:

class CreateSpreadsheetCli < CommandLineBoss
  include CommandLineBoss::HelpOption

  # ...

  private

  include CommandLineBoss::HelpOption

  def banner = <<~BANNER
    Create a spreadsheet

    Usage:
      create_spreadsheet SPREADSHEET_NAME --sheet=SHEET_NAME [--sheet=SHEET_NAME ...]

  BANNER
end

The CreateSpreadsheetCli class is complete!

Use the parser

Now that the command line parser is fully defined, you just need to use it, report errors, and (if successful) do something with the parsed values.

Place the following code at the end of your script file, after the CreateSpreadsheetCli class:

# Parse the command line arguments

options = CreateSpreadsheetCli.new.parse(ARGV)

# Report errors

if options.failed?
  warn options.error_messages.join("\n")
  exit 1
end

# Do something with the result
# In this case just output the command line values

require 'pp'

puts \
  "Creating spreadsheet #{options.spreadsheet_name.pretty_inspect.chomp} " \
  "with sheets #{options.sheet_names.map(&:pretty_inspect).map(&:chomp).join(', ')}"

Run the command line

Should you have a problem running your script, you can compare your script against the expected result which can be found in this project in the file examples/readme_example/create-spreadsheet.

Test your script by running it from the command line. Here are some examples:

Show help output:

$ ./create-spreadsheet --help
Create a spreadsheetasdf

Usage:
  create_spreadsheet SPREADSHEET_NAME --sheet=SHEET_NAME [--sheet=SHEET_NAME ...]

Options:
        --sheet=SHEET_NAME           Name of a sheet to create
    -h, --help                       Show this message

$

A happy-path example:

$ ./create-spreadsheet 'Yearly Sales' --sheet=Summary --sheet=Details
Creating spreadsheet "Yearly Sales" with sheets "Summary", "Details"
$

An example with errors:

$ ./create-spreadsheet
ERROR: A spreadsheet name is required
ERROR: At least one sheet name is required
$

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/main_branch/command_line_boss. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Commit message guidelines

All commit messages must follow the Conventional Commits standard. This helps us maintain a clear and structured commit history, automate versioning, and generate changelogs effectively.

To ensure compliance, this project includes:

• A git commit-msg hook that validates your commit messages before they are accepted.

  To activate the hook, you must have node installed and run npm install.

• A GitHub Actions workflow that will enforce the Conventional Commit standard as part of the continuous integration pipeline.

  Any commit message that does not conform to the Conventional Commits standard will cause the workflow to fail and not allow the PR to be merged.

Pull request guidelines

All pull requests must be merged using rebase merges. This ensures that commit messages from the feature branch are preserved in the release branch, keeping the history clean and meaningful.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the CommandLineBoss project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.