Building a Robust Crystal CLI with OptionParser: A Hands‑On Guide

Desired Outcome

By the end of this guide you will have a compiled Crystal binary that accepts typed flags, required positional arguments, and automatically displays a helpful usage message. You will also know how to validate input, handle errors, and confirm that your CLI behaves as expected.

Prerequisites

• Crystal 1.9 or newer installed (check with crystal --version).
• A basic understanding of Crystal syntax and static typing.
• Access to a terminal and permission to compile binaries.

Step‑by‑Step Procedure

1. Create the Project Skeleton

   Run crystal init app my_cli to generate a new project. Navigate into my_cli and open src/my_cli.cr for editing.

2. Define the OptionParser DSL

   At the top of src/my_cli.cr, import the standard library:

   require "option_parser"
   

   Now declare a parser instance and set a banner that will be shown with -h/--help:

   parser = OptionParser.new do
     banner "Usage: my_cli [options] "
   
     # Flag that expects an integer value
     flag "-n", "--number NUM", "Number of times to repeat" do |num|
       # Convert the string to an Int32; raise if conversion fails
       $repeat_count = num.to_i
     end
   
     # Optional boolean switch
     switch "-v", "--verbose", "Enable verbose output"
   
     # Show help when requested
     on "-h", "--help", "Show this help" do
       puts parser
       exit
     end
   end
   

   Notice the use of a global variable (prefixed with $) to hold parsed values; this keeps the parser block concise.

3. Parse the Arguments

   Invoke parse! to process ARGV. This method removes any flags it consumes, leaving only positional arguments:

   begin
     parser.parse!
   rescue e : OptionParser::ParseError
     puts e.message
     puts parser
     exit 1
   end
   

4. Handle Positional Arguments

   After parsing, ARGV should contain the remaining items. For this example we expect exactly one positional argument: an input file path.

   if ARGV.size != 1
     puts "Error: Exactly one input file is required."
     puts parser
     exit 1
   end
   
   input_file = ARGV[0]
   

5. Implement Core Logic

   With the parsed options in place, write the main functionality. Here we simply print the file name and repeat a message the specified number of times.

   puts "Processing file: #{input_file}"
   
   (count = $repeat_count || 1).times do |i|
     if $verbose
       puts "[#{i+1}/#{count}] Verbose: processing #{input_file}"
     else
       puts "Processing #{input_file}"
     end
   end
   

Expected Checks and Verification

• Help Text: Run ./my_cli --help and confirm the banner and flag descriptions appear.
• Type Validation: Pass a non‑numeric string to --number (e.g., --number abc) and ensure the program exits with a parse error message.
• Positional Argument Integrity: Execute ./my_cli file.txt and verify that ARGV is empty after parsing, meaning no stray arguments remain.
• Verbose Switch: Run ./my_cli -v file.txt and check that the output includes the verbose prefix.

Recovery and Error Handling

OptionParser itself does not enforce required flags. If your tool needs a mandatory option, add a manual check after parse!:

if $repeat_count.nil?
  puts "Error: --number is required."
  puts parser
  exit 1
end

Because parse! mutates ARGV, be careful to perform all flag parsing before accessing positional arguments. Reordering can cause index errors.

Limitations of OptionParser

• It does not support sub‑commands out of the box; you would need to parse the first positional argument as a command and then re‑invoke a new parser.
• Custom type validation beyond simple casts requires explicit code.
• When a flag is defined with a block, the block runs immediately upon encountering the flag; this can complicate ordering if you need to perform actions after all flags are parsed.

Practical Checklist Before Release

1. Compile with crystal build --release src/my_cli.cr.
2. Test the binary on all target platforms (Linux, macOS, Windows).
3. Run ./my_cli --help and verify formatting.
4. Execute unit tests that simulate various flag combinations and validate exit codes.
5. Package the binary with a small README that documents usage.

Conclusion

Crystal’s OptionParser offers a concise, type‑safe way to build command‑line tools. By combining its DSL with static typing, explicit error handling, and post‑parse validation, you can deliver a predictable and user‑friendly interface. Remember to keep flag parsing first, perform manual checks for required options, and test the resulting binary across environments.