Term::CLI::Role::CommandSet - Role for (sub-)commands in Term::CLI


version 0.052003


 package Term::CLI::Command {

    use Moo;



 my $cmd = Term::CLI::Command->new( ... );

 $cmd->callback->( %args ) if $cmd->has_callback;

 if ( $cmd->has_commands ) {
    my $cmd_ref = $cmd->find_command( $cmd_name );
    die $cmd->error unless $cmd_ref;

 say "command names:", join(', ', $cmd->command_names);

 $cmd->callback->( $cmd, %args ) if $cmd->has_callback;

 %args = $cmd->try_callback( %args );


Role for Term::CLI(3p) elements that contain a set of Term::CLI::Command(3p) objects.

This role is used by Term::CLI(3p) and Term::CLI::Command(3p).


This role defines two additional attributes:

commands => ArrayRef

Reference to an array containing Term::CLI::Command object instances that describe the sub-commands that the command takes, or undef.

Note that the elements of the array are copied over to an internal array, so modifications to the ArrayRef will not be seen.

callback => CodeRef

Reference to a subroutine that should be called when the command is executed, or undef.



Predicate functions that return whether or not any (sub-)commands have been added to this object.

callback ( [ CODEREF ] )

CODEREF to be called when the command is executed. The callback is called as:

        status       => Int,
        error        => Str,
        options      => HashRef,
        arguments    => ArrayRef[Value],
        command_line => Str,
        command_path => ArrayRef[InstanceOf['Term::CLI::Command']],



Reference to the current Term::CLI object.


Indicates the status of parsing/execution so far. It has the following meanings:

< 0

Negative status values indicate a parse error. This is a sign that no action should be taken, but some error handling should be performed. The actual parse error can be found under the error key. A typical thing to do in this case is for one of the callbacks in the chain (e.g. the one on the Term::CLI object) to print the error to STDERR.


The command line parses as valid and execution so far has been successful.

> 0

Some error occurred in the execution of the action. Callback functions need to set this by themselves.


In case of a negative status, this will contain the parse error. In all other cases, it may or may not contain useful information.


Reference to a hash containing all command line options. Compatible with the options hash as set by Getopt::Long(3p).


Reference to an array containing all the arguments to the command. Each value is a scalar value, possibly converted by its corresponding Term::CLI::Argument's validate method (e.g. 3e-1 may have been converted to 0.3).


Reference to an array containing all the words on the command line that have not been parsed as arguments or sub-commands yet. In case of parse errors, this often contains elements, and otherwise should be empty.


The complete command line as given to the Term::CLI::execute method.


Reference to an array containing the "parse tree", i.e. a list of object references:


The first item in the command_path list is always the top-level Term::CLI object, while the last is always the same as the OBJ_REF parameter.

The callback is expected to return a hash (list) containing at least the same keys. The command_path, arguments, and options should be considered read-only.

Note that a callback can be called even in the case of errors, so you should always check the status before doing anything.


Return the list of subordinate Term::CLI::Command objects (i.e. "sub-commands") sorted on name.


Return a reference to the object that "owns" this object. This is typically another object class that consumes this Term::CLI::Role::CommandSet role, such as Term::CLI(3p) or Term::CLI::Command(3p), or undef.


add_command ( CMD_REF, ... )

Add the given CMD_REF command(s) to the list of (sub-)commands, setting each CMD_REF's parent in the process.


Return the list of (sub-)command names, sorted alphabetically.

find_matches ( Str )

Return a list of all commands in this object that match the Str prefix.

find_command ( Str )

Check whether Str uniquely matches a command in this Term::CLI object. Returns a reference to the appropriate Term::CLI::Command object if successful; otherwise, it sets the objects error field and returns undef.


    my $sub_cmd = $cmd->find_command($prefix);
    die $cmd->error unless $sub_cmd;

Walks parent chain until it can go no further. Returns a reference to the object at the top. In a functional setup, this is expected to be a Term::CLI(3p) object.

try_callback ( ARGS )

Wrapper function that will call the object's callback function if it has been set, otherwise simply returns its arguments.


Term::CLI(3p), Term::CLI::Command(3p).


Steven Bakker <>, 2018.


Copyright (c) 2018 Steven Bakker

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See "perldoc perlartistic."

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.