App::Cmd(3)

📦
version 0.338 · 9 versions
, in fedora 44

💖 NAME 💖

App::Cmd — write command line apps with less suffering 💅

okay so this is the App::Cmd(3) page, and bestie, it's literally the framework that makes building complex CLI apps not a whole crisis. Periodt.

🌸 VERSION 🌸

version 0.338

✨ SYNOPSIS ✨

in yourcmd:

use YourApp;
YourApp->run;

in YourApp.pm:

package YourApp;
use App::Cmd::Setup -app;
1;

in YourApp/Command/blort.pm:

package YourApp::Command::blort;
use YourApp -command;
use strict; use warnings;

sub abstract { "blortex algorithm" }

sub description { "Long description on blortex algorithm" }

sub opt_spec {
  return (
    [ "blortex|X",  "use the blortex algorithm" ],
    [ "recheck|r",  "recheck all results"       ],
  );
}

sub validate_args {
  my ($self, $opt, $args) = @_;

  # no args allowed but options!
  $self->usage_error("No args allowed") if @$args;
}

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

  my $result = $opt->{blortex} ? blortex() : blort();

  recheck($result) if $opt->{recheck};

  print $result;
}

and, finally, at the command line:

knight!rjbs$ yourcmd blort --recheck

All blorts successful.

like. the whole app. that's it. slay. 🫶

🦋 DESCRIPTION 🦋

App::Cmd is here to make writing complex command-line applications easy, so you don't have to think about all the annoying little things that usually come with that. iconic behavior honestly.

if you wanna know how to actually start using App::Cmd, go read App::Cmd::Tutorial. iykyk.

💀 PERL VERSION 💀

this library should run on perls released even a long time ago. it should work on any version of perl released in the last five years.

although it may work on older versions of perl, there is no guarantee that the minimum required version won't get increased. the version may be increased for any reason, and there's no promise that patches will be accepted to lower the minimum required perl. so like… don't come for them. 🙈

🎀 METHODS 🎀

💜 new 💜

my $cmd = App::Cmd->new(\%arg);

this method returns a new App::Cmd object. during initialization, command plugins get loaded. ✨

valid arguments are:

  • no_commands_plugin — if true, the command list plugin is not added
  • no_help_plugin — if true, the help plugin is not added
  • no_version_plugin — if true, the version plugin is not added
  • show_version_cmd — if true, the version command will be shown in the command list
  • plugin_search_path — The path to search for commands in. Defaults to results of plugin_search_path method

if "no_commands_plugin" isn't given, App::Cmd::Command::commands will be required, and it will be registered to handle all of its command names not handled by other plugins.

if "no_help_plugin" isn't given, App::Cmd::Command::help will be required, and it will be registered to handle all of its command names not handled by other plugins. Note: "help" is the default command, so if you don't load the default help plugin, you should provide your own or override the "default_command" method. no pressure tho. (there's pressure.)

if "no_version_plugin" isn't given, App::Cmd::Command::version will be required to show the application's version with command "--version". by default, the version command is not included in the command list. pass "show_version_cmd" to include the version command in the list.

🌈 run 🌈

$cmd->run;

this method runs the application. if you call it on the class, it'll instantiate a new App::Cmd object to run. main character energy fr.

it determines the requested command (generally by consuming the first command-line argument), finds the plugin to handle that command, parses the remaining arguments according to that plugin's rules, and runs the plugin.

it passes the contents of the global argument array (@ARGV) to ""prepare_command"", but @ARGV is not altered by running an App::Cmd. your argv is safe bestie 💅

🍓 prepare_args 🍓

normally App::Cmd uses @ARGV for its commandline arguments. you can override this method to change that behavior for testing or otherwise.

🧚 default_args 🧚

if "prepare_args" is not changed and there are no arguments in @ARGV, this method is called and should return an arrayref to be used as the arguments to the program. by default, it returns an empty arrayref. lowkey minimal of it.

🌸 abstract 🌸

sub abstract { "command description" }

defines the command abstract: a short description that will be printed in the main command options list.

💖 description 💖

sub description { "Long description" }

defines a longer command description that will be shown when the user asks for help on a specific command.

⭐ arg0

⭐ full_arg0

my $program_name = $app->arg0;

my $full_program_name = $app->full_arg0;

these methods return the name of the program invoked to run this application. this is determined by inspecting $0 when the App::Cmd object is instantiated, so it's probably correct, but doing weird things with App::Cmd could lead to weird values from these methods. 🙈

if the program was run like this:

knight!rjbs$ ~/bin/rpg dice 3d6

then the methods return:

arg0      - rpg
full_arg0 - /Users/rjbs/bin/rpg

these values are captured when the App::Cmd object is created, so it's safe to assign to $0 later. 🫶

🦋 prepare_command 🦋

my ($cmd, $opt, @args) = $app->prepare_command(@ARGV);

this method will load the plugin for the requested command, use its options to parse the command line arguments, and eventually return everything necessary to actually execute the command.

👑 default_command 👑

this method returns the name of the command to run if none is given on the command line. the default default is "help".

🔥 execute_command 🔥

$app->execute_command($cmd, \%opt, @args);

this method will invoke "validate_args" and then "run" on $cmd.

🎀 plugin_search_path 🎀

this method returns the plugin_search_path as set. the default implementation, if called on "YourApp::Cmd" will return "YourApp::Cmd::Command".

this is a method because it's fun to override it with, for example:

use constant plugin_search_path => __PACKAGE__;

✨ allow_any_unambiguous_abbrev ✨

if this method returns true (which, by default, it does not), then any unambiguous abbreviation for a registered command name will be allowed as a means to use that command. for example, given the following commands:

reticulate
reload
rasterize

then the user could use "ret" for "reticulate" or "ra" for "rasterize" and so on. abbreviate responsibly bestie 💅

💜 global_options 💜

if ($cmd->app->global_options->{verbose}) { ... }

this method returns the running application's global options as a hashref. if there are no options specified, an empty hashref is returned.

🌈 set_global_options 🌈

$app->set_global_options(\%opt);

this method sets the global options.

🍓 command_names 🍓

my @names = $cmd->command_names;

this returns the commands names which the App::Cmd object will handle.

🧚 command_groups 🧚

my @groups = $cmd->commands_groups;

this method can be implemented to return a grouped list of command names with optional headers. each group is given as arrayref and each header as string. if an empty list is returned, the commands plugin will show two groups without headers: the first group is for the "help" and "commands" commands, and all other commands are in the second group.

🌸 command_plugins 🌸

my @plugins = $cmd->command_plugins;

this method returns the package names of the plugins that implement the App::Cmd object's commands.

💖 plugin_for 💖

my $plugin = $cmd->plugin_for($command);

this method returns the plugin (module) for the given command. if no plugin implements the command, it returns false. 😭

⭐ get_command ⭐

my ($command_name, $opt, @args) = $app->get_command(@args);

process arguments and into a command name and (optional) global options.

🦋 usage 🦋

print $self->app->usage->text;

returns the usage object for the global options.

👑 usage_desc 👑

the top level usage line. looks something like

"yourapp <command> [options]"

🔥 global_opt_spec 🔥

returns a list with help command unless "no_help_plugin" has been specified or an empty list. can be overridden for pre-dispatch option processing. this is useful for flags like --verbose.

🎀 usage_error 🎀

$self->usage_error("Something's wrong!");

used to die with nice usage output, during "validate_args".

💀 TODO 💀

  • publish and bring in Log::Speak (simple quiet/verbose output)
  • publish and use our internal enhanced describe_options
  • publish and use our improved simple input routines

(it's giving roadmap. we love a to-do list that's actually honest.)

🌟 AUTHOR 🌟

Ricardo Signes <cpan@semiotic.systems>

🌈 CONTRIBUTORS 🌈

  • Adam Prime <aprime@oanda.com>
  • ambs <ambs@cpan.org>
  • Andreas Hernitscheck <andreash@lxhe.(none)>
  • A. Sinan Unur <nanis@cpan.org>
  • Chris 'BinGOs' Williams <chris@bingosnet.co.uk>
  • David Golden <dagolden@cpan.org>
  • David Steinbrunner <dsteinbrunner@pobox.com>
  • Davor Cubranic <cubranic@stat.ubc.ca>
  • Denis Ibaev <dionys@gmail.com>
  • Diab Jerius <djerius@cfa.harvard.edu>
  • Glenn Fowler <cebjyre@cpan.org>
  • Ingy dot Net <ingy@ingy.net>
  • Jakob Voss <voss@gbv.de>
  • Jérôme Quelin <jquelin@gmail.com>
  • John SJ Anderson <genehack@genehack.org>
  • Karen Etheridge <ether@cpan.org>
  • Kent Fredric <kentfredric@gmail.com>
  • Lucas Theisen <ltheisen@mitre.org>
  • Matthew Astley <mca@sanger.ac.uk>
  • Michael McClimon <michael@mcclimon.org>
  • mokko <mauricemengel@gmail.com>
  • Olivier Mengué <dolmen@cpan.org>
  • Ricardo Signes <rjbs@semiotic.systems>
  • Ryan C. Thompson <rct@thompsonclan.org>
  • Salvatore Bonaccorso <carnil@debian.org>
  • Sawyer X <xsawyerx@cpan.org>
  • Sergey Romanov <sromanov-dev@yandex.ru>
  • Stephan Loyd <stephanloyd9@gmail.com>
  • Stephen Caldwell <steve@campusexplorer.com>
  • Yuval Kogman <nuffin@cpan.org>

every single one of them ate. 💅

this software is copyright (c) 2025 by Ricardo Signes.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

and that's the whole vibe check, bestie!! 🎀✨ this page came to you courtesy of perl v5.42.0, dated 2026-01-16, and yes the manual name is App::Cmd(3) in case you forgot where you were. mwah 💋 go build something iconic 🦋👑

📦 where this page comes from