/ 
MooX-Cmd-1.000
River stage two • 14 direct dependents • 19 total dependents
/ MooX::Cmd

NAME

MooX::Cmd - Giving an easy Moo style way to make command organized CLI apps

VERSION

version 1.000

SYNOPSIS

package MyApp;

use Moo;
use MooX::Cmd;

sub execute {
  my ( $self, $args_ref, $chain_ref ) = @_;
  my @extra_argv = @{$args_ref};
  my @chain = @{$chain_ref} # in this case only ( $myapp )
                            # where $myapp == $self
}

1;

package MyApp::Cmd::Command;
# for "myapp command"

use Moo;
use MooX::Cmd;

# gets executed on "myapp command" but not on "myapp command command"
# there MyApp::Cmd::Command still gets instantiated and for the chain
sub execute {
  my ( $self, $args_ref, $chain_ref ) = @_;
  my @chain = @{$chain_ref} # in this case ( $myapp, $myapp_cmd_command )
                            # where $myapp_cmd_command == $self
}

1;

package MyApp::Cmd::Command::Cmd::Command;
# for "myapp command command"

use Moo;
use MooX::Cmd;

# gets executed on "myapp command command" and will not get instantiated
# on "myapp command" cause it doesnt appear in the chain there
sub execute {
  my ( $self, $args_ref, $chain_ref ) = @_;
  my @chain = @{$chain_ref} # in this case ( $myapp, $myapp_cmd_command,
                            # $myapp_cmd_command_cmd_command )
                            # where $myapp_cmd_command_cmd_command == $self
}

package MyZapp;

use Moo;
use MooX::Cmd execute_from_new => 0;

sub execute {
  my ( $self ) = @_;
  my @extra_argv = @{$self->command_args};
  my @chain = @{$self->command_chain} # in this case only ( $myzapp )
                            # where $myzapp == $self
}

1;

package MyZapp::Cmd::Command;
# for "myapp command"

use Moo;
use MooX::Cmd execute_from_new => 0;

# gets executed on "myapp command" but not on "myapp command command"
# there MyApp::Cmd::Command still gets instantiated and for the chain
sub execute {
  my ( $self ) = @_;
  my @extra_argv = @{$self->command_args};
  my @chain = @{$self->command_chain} # in this case ( $myzapp, $myzapp_cmd_command )
                            # where $myzapp_cmd_command == $self
}

1;
package main;

use MyApp;

MyZapp->new_with_cmd->execute();
MyApp->new_with_cmd;

1;

DESCRIPTION

Eases the writing of command line utilities, accepting commands and subcommands and so on. These commands can form a tree, which is mirrored in the package structure. On invocation each command along the path through the tree (starting from the toplevel command through to the most specific one) is instantiated.

Each command needs to have an execute function, accepting three parameters:

self

A reference to the specific MooX::Cmd object that is executing.

args

An ArrayRef of arguments passed to self. This only encompasses arguments of the most specific (read: right-most) command.

chain

An ArrayRef of MooX::Cmds along the tree path, as specified on the command line.

Note that only the execute function of the most specific command is executed.

MooX::Cmd Attributes

Each command has some attributes set by MooX::Cmd during initialization:

command_chain

Same as chain argument to execute.

command_name

The name of the command as found on the command line.

command_commands

HashRef of available subcommands for this command.

command_args

ArrayRef of remaining arguments after command parsing.

command_base

The base namespace for searching subcommand plugins.

Examples

A Single Toplevel Command

#!/usr/bin/env perl
package MyApp;
use Moo;
use MooX::Cmd;

sub execute {
  my ($self,$args,$chain) = @_;
  printf("%s.execute(\$self,[%s],[%s])\n",
    ref($self),                       # which command is executing?
    join(", ", @$args ),              # what where the arguments?
    join(", ", map { ref } @$chain)   # what's in the command chain?
  );
}

package main;
MyApp->new_with_cmd();

Some sample invocations:

$ ./MyApp.pl
MyApp.execute($self,[],[MyApp])

$./MyApp.pl --opt1
MyApp.execute($self,[--opt1],[MyApp])

$ ./MyApp.pl --opt1 arg
MyApp.execute($self,[--opt1, arg],[MyApp])

Toplevel Command with Subcommand

#!/usr/bin/env perl
# let's define a base class containing our generic execute
# function to save some typing...
package CmdBase;
use Moo;

sub execute {
  my ($self,$args,$chain) = @_;
  printf("%s.execute(\$self,[%s],[%s])\n",
    ref($self),
    join(", ", @$args ),
    join(", ", map { ref } @$chain)
  );
}

package MyApp;
# toplevel command/app
use Moo;
use MooX::Cmd;
extends 'CmdBase';

package MyApp::Cmd::frobnicate;
# can be called via ./MyApp.pl frobnicate
use Moo;
use MooX::Cmd;
extends 'CmdBase';

package main;
MyApp->new_with_cmd();

And some sample invocations:

$ ./MyApp.pl frobnicate
MyApp::Cmd::frobnicate.execute($self,[],[MyApp, MyApp::Cmd::frobnicate])

As you can see the chain contains our toplevel command object and then the specific one.

$ ./MyApp.pl frobnicate arg1
MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])

Arguments are passed via the args parameter.

$ ./MyApp.pl some --stuff frobnicate arg1
MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])

Arguments to commands higher in the tree get ignored if they don't match a command.

Access Toplevel Attributes via Chain

#!/usr/bin/env perl
package CmdBase;
use Moo;

sub execute {
  my ($self,$args,$chain) = @_;
  printf("%s.execute(\$self,[%s],[%s])\n",
    ref($self),
    join(", ", @$args ),
    join(", ", map { ref } @$chain)
  );
}

package MyApp;
use Moo;
use MooX::Cmd;
extends 'CmdBase';

has somevar => ( is => 'ro', default => 'someval' );

package MyApp::Cmd::frobnicate;
use Moo;
use MooX::Cmd;
extends 'CmdBase';

around execute => sub {
  my ($orig,$self,$args,$chain) = @_;
  $self->$orig($args,$chain);
  # we can access toplevel attributes via the chain...
  printf("MyApp->somevar = '%s'\n", $chain->[0]->somevar);
};

package main;
MyApp->new_with_cmd();

A sample invocation

$ ./MyApp.pl some --stuff frobnicate arg1
MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])
MyApp->somevar = someval

MooX::Options integration

You can integrate MooX::Options simply by using it and declaring some options, like so:

#!/usr/bin/env perl
package MyApp;
use Moo;
use MooX::Cmd;
use MooX::Options;

option debug => ( is => 'ro' );

sub execute {
  my ($self,$args,$chain) = @_;
  print "debugging enabled!\n" if $self->{debug};
}

package main;
MyApp->new_with_cmd();

A sample invocation

$ ./MyApp-Options.pl --debug
debugging enabled!

Note, that each command and subcommand has its own options., so options are parsed for the specific context and used for the instantiation:

$ ./MyApp.pl --argformyapp command --argformyappcmdcommand ...

THANKS

Jens Rehsack (rehsack)

Co-maintained MooX::Cmd from 2013 to 2017, major contributions to MooX::Cmd::Role, MooX::Cmd::Tester and the test suite

Lukas Mai (mauke), Toby Inkster (tobyink)

Gave some helpful advice for solving difficult issues

Celogeek San

Integration into MooX::Options for better help messages and suit team play

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-moox-cmd/issues.

IRC

Join #web-simple on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

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