Command Decorator

Commands are declared using a decorator to register given functions. Commands are functions with the follow parameters:

Function that will be called when command would be executed.
Type of the command, could be a bash or python command.
Parser arguments for this command.
Command subparser’s keywords, such as description.
class command(func=None, command_type=<Type.PYTHON: 'python'>, args=None, parser_opts=None)[source]

Decorator to register the given functions in a register, along with their command line arguments.

How to use

This decorator allows to be used as a common decorator without arguments, where default type (python) will be used:

def foobar(bar):

Or specifying the type:

def foobar(bar):
    return [['cat', 'foobar']]

But also is possible to provide command line arguments, as expected by argparse.ArgumentParser.add_argument():

@command(args=((('-f', '--foo'), {'help': 'Foo argument that does nothing'}),
               (('--bar',), {'action': 'store_true', 'help': 'Bar argument stored as True'})),
         parser_opts={'title': 'foobar_command', 'help': 'Help for foobar_command'})
def foobar(*args, **kwargs):

For last, is possible to decorate functions or class methods:

class Foo:
    def bar():


Define the type of process to be executed by


Python function executed in a different process. Must implement the function itself.


List of shell commands executed in different processes. Each command must be a list of splitted command such as returned from shlex.split(). As it can execute more than a single command, a list of lists should be returned.


Alias for Shell.


Command line arguments are defined through args parameter of command decorator. This arguments can be defined using the follow structure:

    (('positionals',) {'help': 'Positional arguments', 'nargs': '+'}),
    (('-f', '--foo'), {'help': 'Foo argument', 'default': 'foo'}),
    (('--bar',), {'help': 'Bar argument', 'default': 1, 'type': int, 'choices': range(1, 6)}),
def cmd(*args, **kwargs):

Also is possible to define args using a callable that receives the parser:

def add_arguments(parser):
    parser.add_argument('positionals', help='Positional arguments', nargs='+')
    parser.add_argument('-f', '--foo', help='Foo argument', default='foo')
    parser.add_argument('--bar', help='Bar argument', default=1, type=int, choices=range(1, 6))

def cmd(*args, **kwargs):

Parser options

It is possible to pass options to the command parser, such as title, help… These options should be passed through parser_opts parameter of command decorator:

@command(parser_opts={'help': 'Command doing awesome things!'})
def cmd(*args, **kwargs):


All commands will be registered in a clinner.command.CommandRegister that can be accessed through command.register. Each entry in this register is a dictionary with the fields declared at the beginning of this section.

class CommandRegister[source]

Register for commands.