App::Cmd::Command(3)

💖 App::Cmd::Command — the base class for App::Cmd commands 💖

okay so bestie, this is App::Cmd::Command, and it's basically the blueprint every single command in your App::Cmd app gets built from. It's from the User Contributed Perl Documentation squad. Think of it as the main character template — every command class is giving "I inherit from this" energy. ✨

---

🌸 VERSION 🌸

version 0.338 — that's the vibe check, periodt.

---

🦋 PERL VERSION 🦋

Okay so this library is supposed to run on perl releases from wayyyyy back — like, genuinely a long time ago. The promise is that it should work on any version of perl released in the last five years. 🫶

But here's the fine print, and no cap: it might still work on older perls, but there is no guarantee that the minimum required version won't get bumped. Like, the version can be raised for any reason at all, and there's no promise that patches to lower the minimum required perl will even be accepted. It's giving "we reserve the right to move on." 💅

---

👑 METHODS 👑

🌈 prepare 🌈

my ($cmd, $opt, $args) = $class->prepare($app, @args);

This one is the primary way App::Cmd::Command objects get built, fr fr. You hand it the remaining command line arguments that are meant for the command, and it hands you back:

• the Command object
• the parsed options (as a hashref)
• the remaining arguments (as an arrayref)

And in that usage up there, $app is the App::Cmd object that's doing the invoking. She's the one calling the shots. 💖

🎀 new 🎀

Returns a new instance of the command plugin. Lowkey, only prepare should really be using this one. Everyone else, hands off. 🙈

🔥 execute 🔥

$command_plugin->execute(\%opt, \@args);

This method does whatever it is the command should do! That's the whole assignment, bestie. It gets passed a hash reference of the parsed command-line options and an array reference of the leftover arguments. Go off. 💅

Heads up though: if there's no execute method defined, it'll try to call run instead — but it will warn about this behavior during testing, to remind you to go fix the method name! Not me catching your legacy code in 4K. 😭

⭐ app ⭐

Returns the App::Cmd object that this command is plugged into. That's her home. 🏠

💜 usage 💜

Returns the usage object for this command. (Peep Getopt::Long::Descriptive for the deets.) ✨

🦋 command_names 🦋

Returns a list of command names handled by this plugin. The first item returned is the 'canonical' name of the command. Iconic behavior honestly.

If this method isn't overridden by an App::Cmd::Command subclass, it returns the last part of the plugin's package name, converted to lowercase. Like for example: YourApp::Cmd::Command::Init will, by default, handle the command "init". Slay.

Subclasses should generally get the superclass value of command_names and then append aliases. That's the move. 💅

🌸 usage_desc 🌸

This one should be overridden to provide a usage string. (It's the first argument passed to describe_options from Getopt::Long::Descriptive.)

If you don't override it, it returns "%c COMMAND %o" — and in that, COMMAND is the first item in the result of the command_names method. 🫶

🍓 opt_spec 🍓

This one should be overridden to provide option specifications. (This is the list of arguments passed to describe_options from Getopt::Long::Descriptive, after the first.)

If not overridden, it returns an empty list. Very demure, very mindful, very nothing. 🙈

🧚 validate_args 🧚

$command_plugin->validate_args(\%opt, \@args);

This gets passed a hashref of command line options (as processed by Getopt::Long::Descriptive) and an arrayref of leftover arguments. It may throw an exception — preferably by calling usage_error, below — if they're invalid. Or it may do nothing at all to let processing continue. Your call, bestie. ✨

💀 usage_error 💀

$self->usage_error("This command must not be run by root!");

Call this to die with human-friendly usage output, during validate_args. Polite but lethal. 😭

🌈 abstract 🌈

Returns a short description of the command's purpose. If this method isn't overridden, it'll return the abstract from the module's Pod. And if it can't find the abstract, it goes looking for a comment starting with "ABSTRACT:" — like the ones used by Pod::Weaver::Section::Name. Detective energy. 🔍

👑 description 👑

This one can be overridden to provide the full option description. It's used by the built-in help command.

If it's not overridden, it uses Pod::Usage to extract the description from the module's Pod DESCRIPTION section — or the empty string. Whichever comes first. 🎀

---

✨ AUTHOR ✨

Ricardo Signes <cpan@semiotic.systems> — the icon, the legend. 👑

---

💖 COPYRIGHT AND LICENSE 💖

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 page, bestie!! this one came from perl v5.42.0, dated 2026-01-16, and it's the App::Cmd::Command(3) manpage. go build something iconic with it 💅✨🦋