/ 
CLI-Simple-2.3.0
⭐ Starred 0 / README.md

Table of Contents

NAME

CLI::Simple - a minimalist object oriented base class for CLI applications

SYNOPSIS

#!/usr/bin/env perl

package MyScript;

use strict;
use warnings;

use CLI::Simple::Constants qw(:booleans :chars);
use CLI::Simple qw($AUTO_HELP $AUTO_DEFAULT);

use parent qw(CLI::Simple);

caller or exit __PACKAGE__->main();

sub execute {
  my ($self) = @_;

  # retrieve a CLI option   
  my $file = $self->get_file;
  ...
}

sub list { 
  my ($self) = @_

  # retrieve a command argument
  my ($file) = $self->get_args();
  ...
}

sub main {

  # Disable auto-default for single commands, enable auto-help
  $AUTO_DEFAULT = 0;
  $AUTO_HELP = 1;

  my $cli = MyScript->new(
   option_specs    => [ qw( help format=s file=s) ],
   default_options => { format => 'json' }, # set some defaults
   extra_options   => [ qw( content ) ], # non-option, setter/getter
   commands        => { execute => \&execute, list => \&list,  }
   alias           => { options => { fmt => 'format' }, commands => { ls => 'list' } },
  );

  return $cli->run();
}

1;

# role-based CLI Application (2.0.0)

# create a YAML manifest my-script.yml in your project root:

---
roles:
  frobnicate: My::Script::Role::Frobnicate
  list:       My::Script::Role::List
options:
  - help|h
  - verbose|v
  - output|o=s

# create a main module

package My::Script;

use CLI::Simple qw(:roles);
use parent qw(CLI::Simple);

our $VERSION = '1.0.0';

caller or exit __PACKAGE__->main;

1;

# create implementation roles

package My::Script::Role::Frobnicate;

use Role::Tiny;
use CLI::Simple::Constants qw(:booleans);

sub cmd_frobnicate {
  my ($self) = @_;
  ...
  return $SUCCESS;
}

1;

DESCRIPTION

CLI-Simple

Tired of writing the same 'ol boilerplate code for command line scripts? Want a standard, simple way to create a Perl script that takes options and commands? CLI::Simple makes it easy to create scripts that take options, commands and arguments.

CLI::Simple is designed around the modulino pattern - Perl modules that can be executed directly as scripts. See "MODULINOS".

For common constant values (like $TRUE, $DASH, or $SUCCESS), see CLI::Simple::Constants, which pairs naturally with this module.

Version 2.0.0 introduces optional role-based architecture for applications that have outgrown a single module. Declare your commands and options in a YAML manifest, implement each command in a dedicated Role::Tiny role, and CLI::Simple handles composition, dispatch, and lifecycle automatically. Your main module shrinks to a single line:

caller or exit __PACKAGE__->main;

Not ready for a full refactor? Start smaller. The built-in -dump-spec command introspects your existing module and writes a YAML manifest that makes your configuration data-driven without moving a single line of implementation code. Adopt roles incrementally, one command at a time.

When you are ready to scaffold a full role-based project, -scaffold generates role stubs, a slimmed main module, and inter-module dependencies from your manifest. Feed the resulting tarball to CPAN::Maker::Bootstrapper and you have a complete, buildable CPAN distribution in one step.

Version 2.3.0 adds selective role composition. Commands declared with the roles manifest key compose only the roles required by the selected command. The original commands form remains supported for backward compatibility and retains its original behavior of composing the complete set of command roles.

VERSION

This documentation refers to version 2.3.0.

FEATURES

MODULINOS

A modulino is a Perl module that can also be run directly as a script. The term was coined by Brian D. Foy and the pattern is simple:

caller or exit __PACKAGE__->main();

When the file is required or used by another module, caller returns the calling package and the expression short-circuits - main() is never called. When the file is executed directly by Perl, caller returns false and main() runs. The same file serves as both a reusable module and an executable script.

CLI::Simple is designed around this pattern. Every CLI::Simple application is expected to be a modulino. The framework's lifecycle, internal commands, bash completion, and scaffolding tools all assume this dual-use design.

Why Modulinos?

The modulino pattern offers several advantages over a traditional script:

The Bash Wrapper

Perl modulinos are invoked via a thin bash wrapper script that locates the installed module file and passes all arguments through to Perl:

#!/usr/bin/env bash
#-*- mode: sh; -*-

MODULINO_WRAPPER=my-script
MODULE_NAME=My::Script
MODULE_PATH=$(MODULE_PATH="${MODULE_NAME//:://}.pm" \
  perl -M$MODULE_NAME -e 'print $INC{$ENV{MODULE_PATH}};')

MODULINO_WRAPPER=$MODULINO_WRAPPER perl $MODULE_PATH "$@"

The wrapper locates the installed .pm file via %INC and sets MODULINO_WRAPPER in the environment so CLI::Simple knows the name of the script the user actually typed. This is used by -generate-completion to name the bash completion function correctly and by CPAN::Maker::Bootstrapper to create man page symlinks.

create-modulino

CLI::Simple ships with a create-modulino tool that generates the bash wrapper for any CLI::Simple modulino:

# create wrapper using module name convention (My::Script -> my-script)
create-modulino -m My::Script

# install to a specific directory
create-modulino -m My::Script -i /usr/local/bin

# use a custom wrapper name
create-modulino -m My::Script -a my-alias -i /usr/local/bin

create-modulino is itself a modulino - an example of the pattern it creates. The bash wrapper template lives in its __DATA__ section, keeping the tool entirely self-contained.

If you are building a CPAN distribution, CPAN::Maker::Bootstrapper integrates create-modulino into the make modulino target, generating and installing the wrapper as part of the build process.

MODULINO_WRAPPER

The MODULINO_WRAPPER environment variable tells CLI::Simple the name of the wrapper script that invoked the modulino. It is set by the wrapper and used by:

If MODULINO_WRAPPER is not set, CLI::Simple infers the script name from the module name by convention - My::Script becomes my-script. Set it explicitly when the wrapper name does not follow this convention.

QUICK START

Single-Module Application

The simplest way to use CLI::Simple is to subclass it and define your commands as methods in the same module:

package My::Script;

use strict;
use warnings;

use CLI::Simple::Constants qw(:booleans);

use parent qw(CLI::Simple);

caller or exit __PACKAGE__->main;

sub cmd_frobnicate {
  my ($self) = @_;
  my $output = $self->get_output;
  ...
  return $SUCCESS;
}

sub main {
  __PACKAGE__->new(
    option_specs => [ qw( help|h verbose|v output|o=s ) ],
    commands     => { frobnicate => \&cmd_frobnicate },
  )->run;
}

1;

Role-Based Application

For larger applications, declare your commands and options in a YAML manifest and implement each command in a dedicated Role::Tiny role. Your main module becomes a single declaration:

package My::Script;

use strict;
use warnings;

use CLI::Simple qw(:roles);
use parent qw(CLI::Simple);

our $VERSION = '1.0.0';

caller or exit __PACKAGE__->main;

1;

Naming convention: The YAML manifest filename is derived from your module name - My::Script looks for my-script.yml in the distribution share directory. You must package the spec file with your distribution.

The manifest maps commands to roles:

---
roles:
  frobnicate: My::Script::Role::Frobnicate
  list:       My::Script::Role::List
options:
  - help|h
  - verbose|v
  - output|o=s

Each role implements one or more commands:

package My::Script::Role::Frobnicate;

use Role::Tiny;
use CLI::Simple::Constants qw(:booleans);

sub cmd_frobnicate {
  my ($self) = @_;
  ...
  return $SUCCESS;
}

1;

To easily generate the directory structure, role stubs, and build files for this architecture, CLI::Simple provides a built-in -scaffold tool.

See "-scaffold" for detailed instructions on generating a role-based project tarball from a monolithic script or a YAML manifest. For a comprehensive guide on transitioning your application, see "ROLE-BASED ARCHITECTURE".

ROLE-BASED ARCHITECTURE

CLI::Simple 2.0.0 introduced an optional role-based architecture for applications that have grown beyond a single module. Commands may be implemented in dedicated Role::Tiny roles and declared in a YAML manifest, allowing CLI::Simple to build the dispatch table and provide an inherited main() - potentially reducing your main module to a single declaration.

Version 2.3.0 adds selective role composition through the roles: manifest key. When roles: is used, only the role or roles required by the selected command are composed. The original commands: manifest form remains supported for backward compatibility and retains its original behavior of composing the complete set of command roles.

The YAML Manifest

The manifest is a YAML file that declares your commands, options, and defaults. By convention the filename is derived from your module name:

My::Script                 ->  my-script.yml
CPAN::Maker::Bootstrapper  ->  cpan-maker-bootstrapper.yml

CLI::Simple locates the manifest via File::ShareDir using the distribution name derived from the module name. The manifest must be installed as part of the distribution - it cannot be loaded from an arbitrary location.

Security note: The manifest is loaded exclusively from the distribution share directory via File::ShareDir. A manifest that was not installed as part of the distribution cannot be loaded. This provides the same security model as Perl module loading itself.

Note: Version 2.3.0 introduces roles: for selective role composition. The original commands: form remains supported for backward compatibility. See "roles: vs commands:".

A minimal manifest:

---
roles:
  frobnicate: My::Script::Role::Frobnicate
  list:       My::Script::Role::List
options:
  - help|h
  - verbose|v
  - output|o=s

A complete manifest with all supported keys:

---
roles:
  frobnicate: My::Script::Role::Frobnicate
  list:       My::Script::Role::List
options:
  - help|h
  - verbose|v
  - output|o=s
default_options:
  verbose: 0
extra_options:
  - dbh
  - config_data

Command Values

Entries beneath roles: map a command name to either a single role or a list of roles required by that command.

For example:

roles:
  frobnicate: My::Script::Role::Frobnicate
  publish:
    - My::Script::Role::Publish
    - My::Script::Role::Packages

When frobnicate is selected, only My::Script::Role::Frobnicate is composed into the application.

When publish is selected, both My::Script::Role::Publish and My::Script::Role::Packages are composed.

The selected role set must provide the command method corresponding to the command name. Hyphens are converted to underscores when resolving the method name, so:

code-review

resolves to:

cmd_code_review

The original commands: form remains supported for backward compatibility. Its values may be role class names or method names and retain the pre-2.3.0 behavior described in "roles: vs commands:".

roles: vs commands:

Version 2.3.0 introduces roles: for selective role composition. New applications should use roles:. The original commands: manifest key remains supported for backward compatibility.

With commands:, selecting a command causes all roles referenced by the manifest's command definitions to be composed into the application, regardless of which command is being executed.

This makes methods from every composed role available throughout the application. However, it can also load modules that are not needed by the selected command, increasing startup time.

For applications invoked repeatedly, such as utilities called from make recipes, this additional startup overhead can become significant.

With roles:, only the roles associated with the selected command are composed. A command may require one role or several roles.

Selective composition reduces unnecessary dependencies and makes the role requirements of each command explicit.

When to Use Each Approach

CLI::Simple supports several approaches to organizing command-line applications. The appropriate choice depends on the size of the application and how its commands share functionality.

Applications can migrate from commands: to roles: incrementally, provided each migrated command declares the roles it requires.

Sharing Methods Between Commands

With legacy commands: manifests, all command roles are composed into the application. Methods provided by one command role are therefore available to other commands.

With selective roles: composition, a command cannot assume that roles associated with other commands have been composed.

Functionality shared by multiple commands can be placed in a separate role and included in each command's role list:

roles:
  publish:
    - My::Script::Role::Publish
    - My::Script::Role::Common
  deploy:
    - My::Script::Role::Deploy
    - My::Script::Role::Common

Alternatively, functionality required by every command can be composed directly into the main application class using Role::Tiny::With.

Shared functionality can also be implemented in ordinary Perl modules without using roles.

See "Roles With No Commands" for an example of composing an application-wide role.

Roles With No Commands

Some roles provide application-wide behavior rather than implementing a command. For example, a role may provide an init() method for startup validation or other functionality required by every command.

Because these roles are not associated with a command beneath roles:, they must be composed explicitly into the main module:

package My::Script;

use CLI::Simple qw(:roles);
use Role::Tiny::With;
use parent qw(CLI::Simple);

with 'My::Script::Role::Init';

caller or exit __PACKAGE__->main;

1;

Roles composed this way are always available to the application, regardless of which command is selected.

Activating Role-Based Architecture

Add :roles to your use CLI::Simple statement:

use CLI::Simple qw(:roles);

This causes CLI::Simple to load the YAML manifest and retain its command, role, option, alias, and abbreviation metadata for the application.

Role composition does not occur while the manifest is being loaded.

When the application is started, CLI::Simple first resolves the selected command, including aliases and abbreviations. It then composes the role or roles required by that command.

For commands declared beneath roles:, only the associated role set is composed.

For legacy commands declared beneath commands:, the original all-role composition behavior is retained for backward compatibility.

The Inherited main()

When using :roles, your class inherits main() from CLI::Simple:

caller or exit __PACKAGE__->main;

The inherited main() uses the manifest metadata to resolve the requested command, composes the role or roles required for that command, constructs the application object, and calls run().

Aliases and command abbreviations are resolved before selective role composition, so they select the same role set as the canonical command.

Override main() in your subclass only if you need application startup behavior that cannot be expressed through the manifest, init(), or explicitly composed application roles.

Distributing the Manifest

The YAML manifest is part of the application's runtime configuration and must be installed with the distribution.

CPAN::Maker users can add it to extra-files in buildspec.yml so it is installed into the distribution's share directory:

extra-files:
  - share:
    - my-script.yml

During development the manifest is found via %INC. After installation it is found via File::ShareDir. No code changes are required between the two environments.

PHILOSOPHY AND DESIGN PRINCIPLES

CLI::Simple is intentionally minimalist. It provides just enough structure to build command-line tools with subcommands, option parsing, and help handling -- but without enforcing any particular framework or lifecycle.

Not a Framework

This module is not App::Cmd, MooseX::Getopt, or a full application toolkit. Instead, it offers:

The philosophy is: provide just enough infrastructure, then get out of your way.

Validation, Defaults, and Configuration

CLI::Simple does not impose a validation model. You may:

The lifecycle is explicit and under your control. You decide how much structure you want to add on top of it.

When to Use

CLI::Simple is ideal for:

For interactive CLI handling or complex command trees, consider App::Cmd or CLI::Framework.

The init-run Lifecycle

Opt-in Default Command

By design, CLI::Simple does not impose a default command. This provides total flexibility for the application author:

This "no default by default" behavior is what enables a powerful "setup-only" execution mode. A user can run your script without specifying a command. This will:

This provides an ideal hook for applications that need to perform "on-demand initialization" (e.g., seeding a database, authenticating) by checking for a specific flag inside init(), without also triggering an unwanted command.

In role-based applications using a YAML manifest, a default command that aliases another command should map to the sub name directly rather than a role class:

commands:
  default: cmd_install
  install: My::Module::Role::Installer

$AUTO_HELP and $AUTO_DEFAULT

The following package variables control automatic command selection, help behavior, and output paging.

By default, the framework provides no default command as explained in the sections above. Some scripters may want default behaviors that assume a command or provide usage if no command is provided.

CONSTANTS

CLI::Simple::Constants provides a collection of exportable constants commonly used in command-line applications.

These include:

To use them in your script:

use CLI::Simple::Constants qw(:all);

ADDING USAGE TO YOUR SCRIPTS

To provide built-in usage/help output, include a =head1 SYNOPSIS section in your script's POD:

=head1 SYNOPSIS

```
usage: myscript [options] command args

Options
-------
--help, -h      Display help
...
```

If the user supplies the command help, or the --help option, CLI::Simple displays the configured help sections using Pod::Usage.

For backward compatibility, USAGE is also supported. If a USAGE section is present, it is used as the usage section.

If no USAGE section is present, SYNOPSIS is used instead.

When both SYNOPSIS and USAGE are present, USAGE is used by default. Applications that explicitly configure help_sections may select the desired section.

Customizing Help Output

Custom help() Method

If you need full control over the help output, you can define a custom help method and assign it as a command:

commands => {
  help => &help,
  ...
};

This is useful if your module follows the modulino pattern and you want to present help information that differs from the embedded POD.

help_sections

By default CLI::Simple renders the following POD sections when present, subject to the usage section selection described above:

SYNOPSIS
DESCRIPTION/Commands
DESCRIPTION/Options
OPTIONS

You can override the default selection by passing an array reference of section names during construction:

my $cli = CLI::Simple->new(
  help_sections => [qw(SYNOPSIS COMMANDS OPTIONS)],
  ...
);

When help_sections is supplied explicitly, CLI::Simple honors the list exactly as provided. For example, an application may request both SYNOPSIS and USAGE:

help_sections => [qw(SYNOPSIS USAGE)]

Section names follow Pod::Usage conventions. Subsections are specified with a / separator; for example, DESCRIPTION/Commands renders only the Commands subsection under DESCRIPTION.

INTERNAL COMMANDS

CLI::Simple reserves command names beginning with - for its own use. These commands are intercepted before option parsing begins and execute immediately, bypassing the normal lifecycle entirely. See "The init-run Lifecycle".

Internal commands are dispatched via the %INTERNAL_COMMANDS package variable:

our %INTERNAL_COMMANDS = (
  '-generate-completion' => \&_cmd_generate_completion,
  '-dump-spec'           => \&_cmd_dump_spec,
  '-scaffold'            => \&_cmd_scaffold,
  '-migrate'             => \&_cmd_migrate,
);

Subclasses can add their own internal commands by extending the hash before new() is called:

our %INTERNAL_COMMANDS = (
  %CLI::Simple::INTERNAL_COMMANDS,
  '-my-command' => \&_cmd_my_command,
);

-generate-completion

Generates a bash completion script for the script's commands and options, derived from the live object state. Bash completions are a feature that allows the shell to automatically finish commands, file paths, and options when you press the Tab key.

my-script -generate-completion > \
  ~/.local/share/bash-completion/completions/my-script

After generating the bash completion script, source it in your current shell to test:

source ~/.local/share/bash-completion/completions/my-script

Test by typing your script name followed by a space and pressing Tab. You should see the available commands. To verify option completion, type your script name followed by a space and -- and press Tab.

To make completions permanent, most systems automatically source files placed in ~/.local/share/bash-completion/completions/ when bash-completion 2.x is installed. If your system does not pick them up automatically, add the following to your ~/.bashrc:

source ~/.local/share/bash-completion/completions/my-script

Alternatively, place the generated file in the system-wide completion directory (requires root):

my-script -generate-completion > \
  /etc/bash_completion.d/my-script

The script name is taken from the first argument if provided, then MODULINO_WRAPPER if set, then inferred from the module name. If the inferred name cannot be found in PATH, a warning is issued but the completion script is still generated.

Note: If you created the modulino with the supplied create-modulino tool MODULINO_WRAPPER is already set inside the bash script that invokes the modulino.

-dump-spec

Introspects the running modulino and writes a YAML manifest to the current directory. The filename is derived from the module name by convention.

my-script -dump-spec           # sub names - baby step toward roles
my-script -dump-spec roles     # role class names - full commitment

Without the roles argument, commands map to their existing sub names so the manifest can be used immediately without moving any code. With roles, commands map to derived role class names suitable for use with -scaffold.

Alias commands - those whose coderef resolves to a sub name that does not match the command key - are always written as sub names regardless of mode.

-scaffold

Generates a role-based project tarball from the running modulino or from an explicit spec file.

The -scaffold command can take a monolithic application or a YAML file like the one above and create the project hierarchy for a role based application. The command will create a tarball that contains role stubs, a slimmed main module with extracted POD (if your monolith contained any), a project.mk with inter-module dependencies, and the YAML manifest.

If you've turned your monolith's package into a modulino:

my-script -scaffold                        # introspect live module

...or use cli-simple if you have a .yml file.

cli-simple -scaffold my-script.yml         # scaffold from spec file

The tarball will be named my-script-roles.tar.gz by convention (the lower case snake cased version of the class name). The name is used to infer the class name. If your filename is different than the classes you want to scaffold, you will need to edit the files.

Extract the content to a directory and start editing. If you feed the tarball to CPAN::Maker::Bootstrapper via the import-scaffold command you can produce a complete buildable CPAN distribution.

-migrate

Combines -dump-spec roles and -scaffold in a single step.

my-script -migrate

Writes the YAML manifest then generates the role-based tarball. Use this when you are ready for a full migration and do not need to inspect or edit the manifest first. If you want to review or adjust the manifest before scaffolding, run -dump-spec and -scaffold separately.

METHODS AND SUBROUTINES

new

new( args )

Instantiates a new CLI::Simple instance, parses options, optionally initializes logging, and makes options available via dynamically generated accessors.

Note: The new() constructor uses Getopt::Long's GetOptions, which directly modifies @ARGV by removing any recognized options. The remaining elements of @ARGV are treated as the command name and its arguments.

args is a hash or hash reference containing the following keys:

command

command
command(command)

Gets or sets the command to execute. Usually this is the first argument on the command line after all options have been parsed. There are times when you might want to override the argument. You can pass a new command that will be executed when you call the run() method.

command_args

my $args = $self->command_args();

Gets or sets the argument list. Similar to get_args when no arguments are passed except it returns an array reference.

To replace or add to the argument list, pass an array or list.

my $args = $self->command_args;
$self->command_args(@{$args}, 'foo');

commands

commands
commands(command, handler)

Returns the command dispatch hash supplied to the constructor. When called with a command name and handler, adds the command to the dispatch hash. handler must be a code reference.

commands(foo => sub { return 'foo' });

main

__PACKAGE__->main;

For role-based applications, main is inherited from CLI::Simple and reads the YAML manifest loaded during import. It constructs the object with the manifest's options, default options, extra options, and dispatch table, then calls run().

In a role-based modulino, the entire main sub reduces to:

caller or exit __PACKAGE__->main;

For single-module applications, override main in your subclass as usual.

run

Executes the selected command using the parsed options and arguments. The run method dispatches control to the corresponding command subroutine.

Command subroutines should return 0 for success and a non-zero value for failure. The return value is used as the script's exit status.

get_args

Return the arguments that follow the command.

get_args(NAME, ... )     # with names
get_args()               # raw positional args

With names

Example:

sub send_message {
  my ($self) = @_;

  my %args = $self->get_args(qw(message email));

  _send_message($args{message}, $args{email});
}

When you call get_args with a list of names, values are assigned in order: the first name gets the first argument, the second name gets the second argument, and so on. If you only want specific positions, you may use undef as a placeholder:

my %args = $self->get_args('message', undef, 'cc');  # skip argument 2

If there are fewer positional arguments than names, the remaining names are set to undef. Extra positional arguments (beyond the provided names) are ignored.

With no names

init

If defined, init() is invoked during application initialization, after command-line options and arguments have been processed and before command dispatch. Use this method to perform application-specific initialization and validation.

USING PACKAGE VARIABLES

Constructor arguments may also be defined using package variables. This provides a declarative alternative to passing configuration directly to new().

Package variable names correspond to constructor argument names, converted to uppercase.

our $OPTION_SPECS = [
  qw(
    help|h
    log-level=s|L
    debug|d
  )
];

our $COMMANDS = {
  foo => \&foo,
  bar => \&bar,
};

COMMAND LINE OPTIONS

Command-line options are defined using Getopt::Long-style specifications. You pass these into the constructor via the option_specs parameter:

my $cli = CLI::Simple->new(
  option_specs => [ qw( help|h foo-bar=s log-level=s ) ]
);

Option values are accessible through automatically generated getter methods:

$cli->get_foo();
$cli->get_log_level();

Option names that contain dashes (-) are automatically converted to snake_case for the accessor methods. For example:

option_specs => [ 'foo-bar=s' ]

...results in:

$cli->get_foo_bar();

Getopt::Long Configuration

CLI::Simple uses Getopt::Long to parse command-line options, with the no_ignore_case configuration enabled.

Consequently:

All other Getopt::Long configuration settings retain their defaults.

COMMAND ARGUMENTS

If your commands accept positional arguments, you can retrieve them using the get_args method.

You may optionally provide a list of argument names, in which case the arguments will be returned as a hash (or hashref in scalar context) with named values.

Example:

sub send_message {
  my ($self) = @_;

  my %args = $self->get_args(qw(phone_number message));

  send_sms_message($args{phone_number}, $args{message});
}

If you call get_args() without any argument names, it simply returns all remaining arguments as a list:

my ($phone_number, $message) = $self->get_args;

Note: When called with names, get_args returns a hash in list context and a hash reference in scalar context. =head2 set_args

Resets the positional arguments.

$self->set_args(qw(foo 1));

This method overrides the positional arguments originally passed to the script. You can achieve the same behavior by calling the get_args in scalar context and modifying the reference.

my $args = $self->get_args;
$args->[1] = '2';

Use this technique when you want to modify individual arguments without replacing the entire argument list.

CUSTOM ERROR HANDLER

By default, CLI::Simple exits if Getopt::Long::GetOptions returns a false value, indicating an error while parsing options.

SETTING DEFAULT VALUES FOR OPTIONS

To assign default values to your options, pass a hash reference as the default_options argument to the constructor. These values will be used unless explicitly overridden by the user on the command line.

Example:

my $cli = CLI::Simple->new(
  default_options => { foo => 'bar' },
  option_specs    => [ qw(foo=s bar=s) ],
  commands        => {
    foo => \&foo,
    bar => \&bar,
  },
);

Defaulted options are accessible through their corresponding getter methods, just like options set via the command line.

ADDING ADDITIONAL ACCESSORS

All command-line options are automatically available through getter methods named get_*.

If you need to create additional accessors (getters and setters) for values that are not derived from the command line, use the extra_options parameter.

This is useful for passing runtime configuration or computed values throughout your application.

Example:

my $cli = CLI::Simple->new(
  default_options => { foo => 'bar' },
  option_specs    => [ qw(foo=s bar=s) ],
  extra_options   => [ qw(biz buz baz) ],
  commands        => {
    foo => \&foo,
    bar => \&bar,
  },
);

This will generate get_biz, set_biz, get_buz, etc., for internal use.

LOGGING

CLI::Simple integrates with Log::Log4perl to provide structured logging for your scripts.

CLI::Simple provides convenient initialization of Log::Log4perl through use_log4perl().

__PACKAGE__->use_log4perl(
  level  => 'info',
  config => $log4perl_config_string
);

If you do not explicitly include a log-level option in your option_specs, CLI::Simple will automatically add one for you.

Once enabled, you can access the logger instance via:

my $logger = $self->get_logger;

This logger supports the standard Log4perl methods like info, debug, warn, etc.

Note: Because it is opt-in, CLI::Simple does not itself depend on Log::Log4perl. If your application calls use_log4perl, it owns that dependency and must declare it in its own requires/cpanfile. Static dependency scanners cannot see it -- the module is loaded dynamically inside the method call -- so you must add it by hand.

Colored Output

Pass color => 1 to use_log4perl() to default your script to colorized log output using a built-in appender, instead of supplying your own config:

__PACKAGE__->use_log4perl(
  level => 'info',
  color => 1,
);

Colorizing requires Term::ANSIColor. If it isn't installed, CLI::Simple quietly falls back to uncolored output rather than failing - color => 1 is a request, not a hard dependency.

If you'd like the person running your script to be able to override that default from the command line, add color! to your option_specs:

my @option_specs = qw(
  color!
  ...
);

This gives you --color and --no-color for free. Whichever way use_log4perl() set the default, an explicit flag on the command line always wins; if neither --color nor --no-color is passed, your use_log4perl() setting is left alone. Declaring color! is therefore safe to add at any time - it only changes behavior for scripts whose users actually pass the flag.

Note: color and config are mutually exclusive - use_log4perl() dies if you pass both. color is specifically for using CLI::Simple's own built-in colorized appender; if you need a custom config, write it to include coloring yourself rather than passing color => 1.

Per Command Log Levels

Some commands may require more verbose logging than others. For example, certain commands might perform complex actions that benefit from detailed logs, while others are designed solely to produce clean, structured output.

To assign a custom log level to a command, use an array reference as the value for that command in the commands hash passed to the constructor.

The first two elements of the array reference are:

Example:

CLI::Simple->new(
  option_specs    => [qw( help format=s )],
  default_options => { format => 'json' },  # set some defaults
  extra_options   => [qw( content )],       # non-option, setter/getter
  commands        => {
    execute => \&execute,
    list    => [ \&list, 'error' ],
  }
)->run;

TIP: add other elements to the array for your command to process.

Note: Per-command log levels are not currently supported in the YAML manifest. Define them programmatically by overriding main() if needed.

FAQ

ALIASING OPTIONS AND COMMANDS

CLI::Simple lets you define short, human-friendly aliases for both option names and command names. Use the alias parameter to new():

my $app = CLI::Simple->new(
  option_specs    => [ qw(config=s verbose!) ],
  commands        => { list => \&list, execute => \&execute },
  alias => {
    options  => { cfg => 'config', v => 'verbose' },
    commands => { ls  => 'list'   }
  },
);

How option aliases work

How command aliases work

Usage examples

# Using an option alias
script.pl --cfg app.json execute

# Using a command alias
script.pl ls

After parsing, both get_config() and get_cfg() will return the same value. If the user passes both --config and --cfg, the value from --config (the canonical version) is used.

Note: In role-based applications using a YAML manifest, command aliases are expressed by mapping the alias command directly to the target sub name rather than a role class. See "ROLE-BASED ARCHITECTURE".

Recommendations

ERRORS/EXIT CODES

The run() method dispatches the selected command and returns its exit status. Command handlers should return 0 for success or a non-zero value to indicate failure.

exit CLI::Simple->new(commands => { foo => \&cmd_foo })->run();

Exit Codes

CLI::Simple uses conventional exit codes so that calling scripts can distinguish between normal completion and error conditions.

LICENSE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See https://dev.perl.org/licenses/ for more information.

SEE ALSO

Getopt::Long, CLI::Simple::Constants, CLI::Simple::Utils, Pod::Usage, App::Cmd, CLI::Framework, Role::Tiny, CPAN::Maker::Bootstrapper

AUTHOR

Rob Lauer - rlauer@treasurersbriefcase.com