NAME

CLI::Cmdline - Minimal command-line parser with short/long options and aliases in pure Perl

VERSION

1.20

SYNOPSIS

use CLI::Cmdline qw(parse);

my $switches = '-v -q -h|help --dry-run';
my $options  = 'input --output --config --include';

# only define options which have no default value 0 or '';
my %opt = (
    include => [],         # multiple values allowed
    config  => '/etc/myapp.conf',
);

CLI::Cmdline::parse(\%opt, $switches, $options)
    or die "Usage: $0 [options] <files...>\nTry '$0 --help' for more information.\n";

# @ARGV now contains only positional arguments
die " .... "   if $#ARGV < 0 || $ARGV[0] ne 'file.txt';

DESCRIPTION

Tiny, zero-dependency command-line parser supporting short/long options, aliases, bundling, repeated switches, array collection, and -- termination.

• Short options: -v, -vh, -header

• Long options: --verbose, --help

• Long options with argument: --output file.txt or --output=file.txt

• Aliases via |

• Optional leading - or -- in specification strings

• Single-letter bundling: -vh, -vvv, -vd dir

• Switches counted on repeat

• Options collect into array only if default is ARRAY ref

• -- ends processing

• On error: returns 0, restores @ARGV

• On success: returns 1

EXAMPLES

Minimal example – switches without explicit defaults

You do not need to pre-define every switch with a default value. Missing switches are automatically initialized to 0.

my %opt;
parse(\%opt, '-v -h -x')
    or die "usage: $0 [-v] [-h] [-x] files...\n";

# After parsing ./script.pl -vvvx file.txt
# %opt will contain: (v => 3, h => 0, x => 1)
# @ARGV == ('file.txt')

Required Options

To make an option required, declare it with an empty string default and check afterward:

my %opt = ( mode => 'normal');
parse(\%opt, '', '--input --output --mode')
    or die "usage: $0 --input=FILE [--output=FILE] [--mode=TYPE] files...\n";

die "Error: --input is required\n"   if ($opt{input} eq '');

Collecting multiple values, no default array needed

If you want multiple occurrences but don't want to pre-set an array:

my %opt = (
    define => [],        # explicitly an array ref
);

parse(\%opt, '', '--define')
    or die "usage: $0 [--define NAME=VAL ...] files...\n";

# ./script.pl --define DEBUG=1 --define TEST --define PROFILE
# $opt{define} == ['DEBUG=1', 'TEST', 'PROFILE']

# Alternative: omit the default entirely (parser will not auto-create array)
# If you forget the [] default, repeated --define will overwrite the last value.

Realistic full script with clear usage message

#!/usr/bin/perl
use strict;
use warnings;
use CLI::Cmdline qw(parse);

my $switches = '-v -q --help --dry-run -f';
my $options  = '--input --output --mode --tag';

my %opt = (
    mode    => 'normal',
    tag     => [],            # multiple tags allowed
);

parse(\%opt, $switches, $options)
    or die <<'USAGE';
Usage: process.pl [options] --input=FILE [files...]

Options:
  -v                        Increase verbosity (repeatable)
  -q                        Suppress normal output
  --dry-run                 Show what would be done
  -f                        Force operation even if risky
  --input=FILE              Input file (required)
  --output=FILE             Output file (optional)
  --mode=MODE               Processing mode (normal|fast|safe)
  --tag=TAG                 Add a tag (multiple allowed)
  --help                    Show this help message

Example:
  process.pl --input=data.csv --output=result.json --tag=2026 --tag=final -vv
USAGE
if ($opt{h}) {
    print <<'HELP';
Full documentation goes here...
HELP
    exit 0;
}

if (!defined $opt{input}) {
    die "Error: --input is required. See --help for usage.\n";
}

my $verbosity = $opt{v} - $opt{q};
print "Starting processing (verbosity $verbosity)...\n" if $verbosity > 0;

Using -- to pass filenames starting with dash

my %opt;
parse(\%opt, '-r')
    or die "usage: $0 [-r] files...\n";

# Command line:
./script.pl -r -- -hidden-file.txt another-file

# Results:
# $opt{r} == 1
# @ARGV == ('-hidden-file.txt', 'another-file')

AUTHOR

Hans Harder <hans@atbas.org>

LICENSE

This module is free software.

You can redistribute it and/or modify it under the same terms as Perl itself.

See the official Perl licensing terms: https://dev.perl.org/licenses/