Parsing Command Line Arguments with OptionParser

Published 2023-10-03. Last modified 2025-08-08.
Time to read: 9 minutes.

This page is part of the ruby collection.

The Ruby language has many libraries for parsing command-line arguments. This article discusses OptionParser, which is one of the most popular Ruby libraries for parsing arguments. OptionParser is popular because it is both powerful and easy to use, and it is part of the Ruby runtime library.

This is the OptionParser GitHub repository.

Documentation

The detailed Ruby documentation for OptionParser is here. I am not going to restate the documentation, since many articles have been written about OptionParser. Instead, this section will just discuss important details that are not usually discussed, or are assumed by many writers to be obvious, even though the omitted details might not be obvious to many readers.

Firstly, OptionParser returns parsed values in a hash.

Denoting Keyword Options

Options can merely be keywords, for example an option such as -f (--force) might be used to specify that any previous output from a program should be overwritten. Keywords are actually implemented as a key/value pair with value true.

Ruby code fragment

options = {}
OptionParser.new do |parser|
  parser.on '-f', '--force'
end.order!(ARGV, into: options)

If the program containing OptionParser code is launched with the -f option, the above code fragment would store {force: true} in the options hash.

The name force is used because that is the long form name of the option.

Name/Value Options

Options with arbitrary values can also be defined, and they are also stored as key/value pairs.

For example, an option named verbose might require a string value such as low, medium or high. In the following minimal example, the default value for verbose is 'low'. The presence of a placeholder, in this example VERBOSE, indicates that the parsed value should be stored in the result hash with a key named after the long option name. The placeholder value is not actually relevant, and its length is also unimportant; the Ruby documentation calls placeholders dummy tokens.

Ruby code fragment

options = { verbose: 'low' }
OptionParser.new do |parser|
  parser.on '-v', '--verbose=VERBOSE'
end.order!(ARGV, into: options)

The following code fragment is functionally identical to the previous even though the value of the placeholder / dummy token is different.

Equivalent Ruby code fragment

options = { verbose: 'low' }
OptionParser.new do |parser|
  parser.on '-v', '--verbose=ABC'
end.order!(ARGV, into: options)

As before, the name verbose is used for the name of the resulting entry in the resulting hash because the long form of the option is --verbose. The value placeholder is shown in yellow. You could also write the above as follows, but there is no reason to do so because specifying the value placeholder twice just represents more typing:

Ruby code fragment

options = { verbose: 'low' }
OptionParser.new do |parser|
  parser.on '-v VERBOSE', '--verbose=VERBOSE'
end.order!(ARGV, into: options)

Positional Parameters Delimit Options

The documentation does not mention a crucial limitation of how OptionParser parses command lines:

Option parsing stops on the first positional parameter.

A positional parameter is a token that does not begin with a dash and is not an option value.

This means, for example, that the first two options in the following command line are parsed, but the remaining options are not, unless the command line is manipulated:

Shell

$ my_program -o --option=value positional_parameter -p -q --another-option=value2

Subcommands that follow the above syntax are fully discussed in the OptionParser documentation. Later in this article I discuss why the above syntax is unnecessarily awkward for the user, and in NuGem I discuss an alternative, NestedOptionParser, based on a novel usage of OptionParser that is more user-friendly.

Sod

The F/OSS library called sod enhances OptionParser. Although sod can be used as an OptionParser wrapper that provides enhanced capability, you can also just use selected features of sod while continuing to use OptionParser as usual. That is the approach taken in this article. One sod feature that I especially like is the extra data types that it supports for parsing arguments:

Pathname returns a Pathname instance.
Version returns a Versionaire::Version instance.
Custom parsers are possible that return arbitrary data types.

Installation

OptionParser is part of the standard Ruby runtime library, so once Ruby itself is installed, there are no mandatory additional steps for installation.

Gemfile

If you are building an application, add the following lines to your application’s Gemfile:

Gemfile

gem 'optparse'
gem 'sod' # If you want extra datatypes

And then execute:

Shell

$ bundle

Gem

If you are building a gem, add the following line to your gem’s .gemspec:

your_gem.gemspec

spec.add_dependency 'optparse'
spec.add_dependency 'sod' # If you want extra datatypes

And then execute:

Shell

$ bundle

Usage

My stabilize_video program is an example of how I like to use OptionParser. Below are portions of three Ruby source files:

option.rb parses the options and generates the help text.
stabilize_video.rb parses the positional parameters.
stablize.rb receives the positional parameters and options.

The following import is required before invoking creating an OptionParser instance:

Ruby code fragment

require 'optparse'
require 'sod' # If you want to use sod
require 'sod/types/pathname' # If you want to parse Pathnames

Parsing Options

Let’s look at an initial version of the parse_options method, which uses OptionParser to parse the optional arguments. Later in this article I show a more flexible implementation that allows the parsing code to be testable.

Portion of options.rb

def parse_options
  options = { shake: 5, loglevel: 'warning' }
  OptionParser.new do |parser|
    parser.program_name = File.basename __FILE__
    @parser = parser

    parser.on('-f', '--overwrite', 'Overwrite output file if present')
    parser.on('-l', '--loglevel LOGLEVEL', Integer, "Logging level (#{VERBOSITY.join ', '})")
    parser.on('-s', '--shake SHAKE', Integer, 'Shakiness (1..10)')
    parser.on('-v', '--verbose VERBOSE', 'Verbosity')
    parser.on('-z', '--zoom ZOOM', Integer, 'Zoom percentage')

    parser.on_tail('-h', '--help', 'Show this message') do
      help
    end
  end.order!(into: options)
  help "Invalid verbosity value (#{options[:verbose]}), must be one of one of: #{VERBOSITY.join ', '}." if options[:verbose] && !options[:verbose] in VERBOSITY
  help "Invalid shake value (#{options[:shake]})." if options[:shake].negative? || options[:shake] > 10
  options
end

The default options are set in the highlighted hash. Default values are set for the :shake and :loglevel keys.
When parser.on is passed the name of an option value in UPPER CASE, it creates an entry in the options hash with that name, in lower case. The above code shows the following examples:
- LOGLEVEL provides a means for the user to specify a value to replace the default value of the loglevel entry in the options hash, which was initialized with the string value 'warning'.
- SHAKE provides a means for the user to specify a to replace the default value of the shake entry in the options hash, which was initialized with the integer value 5.
- VERBOSE provides a means for the user to specify a string value for a new entry in the options hash, with the key verbose.
- ZOOM provides a means for the user to specify a string value for a new entry in the options hash, with the key zoom.
OptionParser.order! has the side effect that option keywords and key/value pairs that match parser.on statements are removed from ARGV.
Ending the end.order! statement with (into: options) causes the parsed option key/value pairs to be added or updated in the hash called options.
The parsed options are returned.

Parsing Positional Parameters

Let’s see how stabilize_video.rb parses positional parameters:

stabilize_video.rb

require 'colorator'
require_relative 'stabilize_video/version'
require_relative 'options'

# Require all Ruby files in 'lib/', except this file
Dir[File.join(__dir__, '*.rb')].each do |file|
  require file unless file.end_with?('/stabilize_video.rb')
end

def main
  options = parse_options
  help 'Video file name must be provided.' if ARGV.empty?
  help "Too many parameters specified.\n#{ARGV}" if ARGV.length > 1
  video_in = ARGV[0]
  video_out = "#{File.dirname video_in}/stabilized_#{File.basename video_in}"
  StablizeVideo.new(video_in, video_out, **options).stabilize
end

main

Here are some notes to help you understand the above code:

Usage of colorator or rainbow to output colored strings helps readability but is not required.
Because OptionParser removes each argument from ARGV that it recognizes, when it finishes all that should be left on the command line are the positional parameters. The main method calls parse_options, which as we know calls OptionParser, and then ensures that a mandatory filename parameter is provided.
parse_options returns a hash of name/value pairs, which can optionally be passed when doubly dereferenced with two asterisks (**options). This is done in the highlighted code above when creating a new StablizeVideo instance.

Passing Options

In the following code, the optional values returned by parse_options are provided to the StablizeVideo.initialize method. Once again, double asterisks are used.

Portion of stabilize.rb

  def initialize(video_in, video_out, **options)
    @options   = options
    @loglevel  = "-loglevel #{options[:loglevel]}"
    @loglevel += ' -stats' unless options[:loglevel] == 'quiet'
    @shakiness = "shakiness=#{options[:shake]}"
    @video_in  = MSUtil.expand_env video_in
    @video_out = MSUtil.expand_env video_out
    unless File.exist?(@video_in)
      printf "Error: file #{@video_in} does not exist.\n"
      exit 2
    end
    unless File.readable? @video_in
      printf "Error: #{@video_in} cannot be read.\n"
      exit 2
    end
    return unless File.exist?(@video_out) && !options.key?(:overwrite)

    printf "Error: #{@video_out} already exists.\n"
    exit 3
  end

Notice in the above code that:

The value of the -l / --loglevel option is obtained from options[:loglevel].
The value of the -s / --shake option is obtained from options[:shake].
If the user specified the -f (--overwrite) option, that is detected by options.key?(:overwrite).

Hand-written Help Text

I find that using the automatically generated help text results in a more complex program for little gain, because there are so many moving parts to keep track of. Explicitly writing the help method is a more maintainable way of showing the user what they need to know.

The help method below generates the help text, which might be preceded with an error message.

Portion of options.rb

def help(msg = nil)
  printf "Error: #{msg}\n\n".yellow unless msg.nil?
  msg = <<~END_HELP
    stabilize: Stabilizes a video using the FFmpeg vidstabdetect and vidstabtransform filters.

    Syntax: stabilize [Options] PATH_TO_VIDEO

    Options:
      -f Overwrite output file if present
      -h Show this help message
      -s Shakiness compensation 1..10 (default 5)
      -v Verbosity; one of: #{VERBOSITY.join ', '}
      -z Zoom percentage (computed if not specified)

    See:
      https://www.ffmpeg.org/ffmpeg-filters.html#vidstabdetect-1
      https://www.ffmpeg.org/ffmpeg-filters.html#toc-vidstabtransform-1
  END_HELP
  printf msg.cyan
  exit 1
end

A Ruby squiggly heredoc is used to store a multiline string as the help text.

Running the Program

Now let's run the above program and view the generated help text:

Shell

$ stabilize -h
stabilize -h
  stabilize: Stabilizes a video using the FFmpeg vidstabdetect and vidstabtransform filters.

  Syntax: stabilize [Options] PATH_TO_VIDEO

  Options:
    -f Overwrite output file if present
    -h Show this help message
    -s Shakiness compensation 1..10 (default 5)
    -v Verbosity; one of: trace, debug, verbose, info, warning, error, fatal, panic, quiet
    -z Zoom percentage (computed if not specified)

  See:
    https://www.ffmpeg.org/ffmpeg-filters.html#vidstabdetect-1
    https://www.ffmpeg.org/ffmpeg-filters.html#toc-vidstabtransform-1

Testing Argument Parsing

As we have seen, Ruby passes an argument to the OptionParser block body. As a reminder, the following code shows the block body and the argument, called parser:

Ruby code

OptionParser.new do |parser|
  # OptionParser block body
end

Designing Parsing Code for Testability

The argument provided to the OptionParser block body, called parser, is an OptionParser instance. There are two ways to supply a value for ARGV, other than the default value that Ruby provides.

The OptionParser provides methods called parse, parse!, option and option!. All of these methods accept an optional argv parameter.
The first optional argument of each of these methods is the array of arguments to be parsed. The value of this argument defaults to ARGV, which the the operating system passes to your Ruby program when it starts.

The following Ruby code defines a method called parse_options that demonstrates a technique for command-line option parsing. Key features of this technique are:

Default values can be established in a modular fashion
Option parsing code is more modular, which makes it easier to understand
OptionParser functionality is not affected
System-provided values can be overridden for testing
Nothing extra required for full RSpec support

I intend to use this latest iteration of the technique in all my scripts and CLI tools.

Ruby code

require 'optparse'

def parse_options(default_options, argv: ARGV)
  options = default_options
  OptionParser.new do |parser|

    # Remaining parameter parsing code goes here
    # For example:
    parser.on '-v', '--verbose', FalseClass
  end.order! argv, into: options
  options
end

The parse_options method accepts one or two arguments: default_options, which is a hash containing default values for options, and the optional argv argument, which allows you to specify a custom array of arguments to parse instead of the default system ARGV provided by Ruby.

The parse_options method body initializes a new automatic variable called options from the default_options parameter. A new OptionParser instance is then created called parser. It’s scope is only within the OptionParser body. The odd syntax of within this method body actually does the parsing of the arguments, and then stores the results in the options hash. If the parameter list does not specify an option, the default value remains intact, otherwise the default value is overwritten.

The highlighted line within the OptionParser body is important: this code tells the parser to use the optional argv array, if provided, as the source of command-line arguments. This technique is useful for testing and for programmatically specifying arguments.

Define the options that your script accepts within the remainder of the parser block. The example recognizes a -v or --verbose flag. After instantiating the OptionParser instance called parser, the end closes the OptionParser constructor block, which finalizes the parsing process. The order! method is then called with an option called into:, followed by the name of the variable that will receive the hash resulting from the parsing operation that just completed.

Finally, the parse_options method returns the populated options hash. It is up to the caller to handle any remaining arguments in ARGV.

Testing the Parsing Code With irb

The following example invocation demonstrates how to call parse_options with a set of default options and a custom argument String array, simulating command-line input.

The demonstrated approach shows how to make option parsing flexible and testable. You can easily override the arguments without going through the pain of providing actual command lines to running instances of your code, or getting frustrated with Visual Studio Code’s inability to accept ARGV tokens with embedded spaces.

The following example shows how to use the parse_options method above. You might write code like this for unit tests of CLI user invocation. This example simulates a CLI being called with two positional parameters (param1 and param2), and without an optional parameter (-v / --verbose) being provided.

Example of calling parse_options

irb(main):001* require 'optparse'

irb(main):002* default_options = {
irb(main):003*   param1: 'value_1',
irb(main):004*   param2: 'value_2'
irb(main):005> }
=> {:param1=>"value_1", :param2=>"value_2"}

irb(main):006> my_argv = %w[param1 value_3 param2 value_4]
=> ["param1", "value_3", "param2", "value_4"] 

irb(main):006>  parse_options default_options, argv: my_argv
{:param1=>"value_1", :param2=>"value_2"}

You can write RSpec unit tests that incorporate similar code. This allows you to test CLI argument parsing easily.

Testing with RSpec

The following code shows an RSpec test that parses an argument as a Ruby Time instance.

Ruby code

require 'optparse'
require 'optparse/time'
require_relative 'spec_helper'

class NestedOptionParserTest
  RSpec.describe OptionParser do
    option_parser = described_class.new do |parser|
      parser.on('-t TIME', '--time=TIME', Time)
      parser.on('-x', '--xray')
    end

    it 'initializes an OptionParser' do
      options = { time: '2020-02-12T00:00:00Z' } # Default value of all options
      option_parser.order! %w[-x -t 2025-07-01T12:00:00Z], into: options
      expect(options).to eq({ xray: true, time: Time.parse('2025-07-01T12:00:00Z') })
    end
  end
end

Highline

Highline is a gem that is often found in CLIs that are built with OptionParser. It provides a way to ask the user questions and get answers, similar in syntax to methods that Thor provides for the same purpose.

The agree method is particularly useful. Both the agree and ask methods have an undocumented feature: Putting a space at the end of the question string suppresses the newline between the question and the answer.

The optional character parameter causes the first character that the user types to be immediately processed without requiring them to press Enter.

my_cli.rb

$ irb
irb(main):001> require 'highline'
=> true
irb(main):002* begin
irb(main):003* printf "Work work work"
irb(main):004> end while HighLine.agree "\nAll done! Do you want to do it again? ", character = true
Work work work
All done! Do you want to do it again?
Please enter "yes" or "no".
All done! Do you want to do it again? y
Work work work
All done! Do you want to do it again? y
Work work work
All done! Do you want to do it again? n
=> nil
irb(main):005>

Below is some code that I wrote for Nugem. The import statement imports the methods of the Highline library directly into the current namespace.

highline_wrappers.rb

require 'highline/import'

module HighlineWrappers
  def yes_no?(prompt = 'More?', default_value: true)
    answer_letter = ''
    suffix = default_value ? '[Y/n]' : '[y/N]'
    default_letter = default_value ? 'y' : 'n'
    until %w[y n].include? answer_letter # rubocop:disable Performance/CollectionLiteralInLoop
      answer_letter = ask("#{prompt} #{suffix} ") do |q|
        q.limit = 1
        q.case = :downcase
      end
      answer_letter = default_letter if answer_letter.empty?
    end
    answer_letter == 'y'
  end

  # Invokes yes_no? with the default answer being 'no'
  def no?(prompt = 'More?')
    yes_no? prompt, default: false
  end

  # Invokes yes_no? with the default answer being 'yes'
  def yes?(prompt = 'More?')
    yes_no? prompt, default: true
  end
end

The above code can be mixed into any class or module. They ask the user a question and return true or false based on the user’s response.

The methods in the code issue a prompt and then read just one character from the user. The user can respond by typing the single character y to answer “yes”, or n to answer “no”. If the user presses Space or Enter without typing anything else, the default answer is used.

The following irb session shows how to use the yes? and no? methods.

irb session

irb(main):152> yes? 'asdf'
asdf [Y/n] Enter or Space
=> true

irb(main):153> yes? 'asdf'
asdf [Y/n] n
=> false

irb(main):154> no? 'asdf'
asdf [y/N] Enter or Space
=> false

irb(main):155> no? 'asdf'
asdf [y/N] n
=> false

irb(main):156> no? 'asdf'
asdf [y/N] y
=> true

Subcommand Options

This section is incomplete, and the version of nugem described here is still under development. I am working on a major new release for nugem at present.

The documentation shows how to setup your code so subcommands can share common options, and also have options specific to certain subcommands. This is how most information on the interwebs says how subcommand options should be organized:

Most commonly recommended form of subcommand options

COMMAND [GLOBAL FLAGS] [SUB-COMMAND [SUB-COMMAND FLAGS]]

For example, the nugem CLI has two subcommands: ruby and jekyll.

The --loglevel, --executable and --help options are available for all subcommands.
The ruby subcommand has no special options.
The --tags and --hooks options are only for the jekyll subcommand.

Using the documentated way of implementing subcommand option parsing, the following syntaxes would be allowed:

Allowed syntaxes

nugem --help
nugem ruby
nugem --loglevel info ruby
nugem --executable ruby
nugem --loglevel info --executable ruby
nugem jekyll
nugem jekyll --tags
nugem jekyll --tags --hooks
nugem --loglevel info jekyll --tags --hooks
nugem --loglevel info --executable jekyll --tags --hooks
... and others ...

The most commonly recommended approach requires that common options must precede the subcommand, and subcommand options must follow the subcommand. The following desirable syntaxes would therefore not be allowed:

Forbidden syntaxes

nugem ruby --executable
nugem jekyll --executable
nugem --tags jekyll
nugem --tags jekyll --executable
nugem jekyll --executable --tags
... and others ...

Here is a rough outline of how to implement this type of syntax:

Ruby code

global = OptionParser.new do |opts|
  # on statements for flags common to all commands go here
end

subcommands = {
  'foo' => OptionParser.new do |opts|
    # on statements for the foo command go here
  end
  'baz' => OptionParser.new do |opts|
    # on statements for the baz command go here
  end
}

global.order!
subcommands[ARGV.shift].order!

The last two lines of the above code shows how global.order! parses all options in the first element of ARGV until the first token that doees not start with a dash, and removes them from ARGV.

The next line, subcommands[ARGV.shift].order!, parses and removes all options after the subcommand.

I do not like this syntax.

I prefer to order options before positional parameters, and to be able to specify options in any order, anywhere on the command line. However, this makes parsing multiple subcommands difficult.

A more practical approach would be to mandate that the first parameter must be the subcommand name, followed by options and any other positional parameters.

Forbidden syntaxes

nugem ruby --executable
nugem ruby --executable
nugem jekyll --tags
nugem jekyll --tags --executable
nugem jekyll --executable --tags
... and others ...

OptionParser on statements typically match specific flags or options. However, to match all options, regardless of their name or format, write the on statement as a custom order block:

Separating keywords from options

def separate_keywords_from_options
  @keywords      = ARGV.reject { |x| x.start_with? '-' }
  @argv = ARGV.select { |x| x.start_with? '-' }
end

Common option parsing

def parse_common_options(argv)
  OptionParser.new do |parser|
    parser.default_argv = argv
    parser.on '-e', '--executables', 'Include an executable'
    parser.on '-v', '--verbose', FalseClass
  end.order! into: @options
end

Subcommand option parsing

def parse_subcommand_ruby(argv)
  OptionParser.new do |parser|
    parser.default_argv = argv
    parser.on '-j', '--jump', 'Jump for joy'
    parser.on '-s', '--skip', 'Skip around'
  end.order! into: @options
end

process_keywords

def process_keywords(keywords)
  puts "Keywords are: #{keywords.join ', '}"
end

Ruby code

require 'optparse'

@argv = []
@options = {}
separate_keywords_from_options
parse_common_options @argv
parse_subcommand_ruby @argv
puts "Options: #{@options}"
puts "keywords: #{@keywords}"
process_keywords @keywords

Mainframe image; Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 License by PekoeBlaze

© Copyright 1994-2025 Michael Slinn. All rights reserved.
For requests to use this copyright-protected work in any manner, email mslinn@mslinn.com.

This website was made using Jekyll and Mike Slinn’s Jekyll Plugins.