Registering functions

Once you’ve defined your functions, you need to register them with a CLI instance.

You can register as many functions as you like with the CLI instance.

from targ import CLI

def add(a: int, b: int):
    print(a + b)

def subtract(a: int, b: int):
    print(a - b)

if __name__ == "__main__":
    cli = CLI()


You can also register coroutines, as well as normal functions:

 import asyncio

 from targ import CLI

 async def timer(seconds: int):
     print(f"Sleeping for {seconds}")
     await asyncio.sleep(seconds)

if __name__ == "__main__":
   cli = CLI()


You can specify aliases for each command, which can make your CLI more convenient to use. For example, an alias could be an abbreviation, or a common mispelling.

from targ import CLI

def add(a: int, b: int):
    print(a + b)

if __name__ == "__main__":
    cli = CLI()
    cli.register(add, aliases=['+', 'sum'])

Both of the following will now work:

python add 1 1
python + 1 1
python sum 1 1


You can add your functions / coroutines to a group:

cli.register(say_hello, 'greetings')
cli.register(add, 'maths')

And then call them as follows:

python greetings say_hello 'bob'
python maths add 1 2

Overriding the command name

By default the command name is the name of the function being registered. However, you can choose to override it:

cli.register(add, command_name='sum')


By default, targ will print out an abbreviated error message if it encounters a problem. To see the full Python traceback, pass in the --trace argument.

python maths add 1 'abc' --trace

Solo mode

Sometimes you’ll just want to register a single command with your CLI, in which case, specifying the command name is redundant.

from targ import CLI

def add(a: int, b: int):
    print(a + b)

if __name__ == "__main__":
    cli = CLI()

You can then omit the command name:

python 1 1


class targ.CLI(description: str = 'Targ CLI')

The root class for building the CLI.

Example usage:

cli = CLI()

description – Customise the title of your CLI tool.

command_exists(group_name: str, command_name: str) bool

This isn’t used by Targ itself, but is useful for third party code which wants to inspect the CLI, to find if a command with the given name exists.

register(command: Callable, group_name: Optional[str] = None, command_name: Optional[str] = None, aliases: List[str] = [])

Register a function or coroutine as a CLI command.

  • command – The function or coroutine to register as a CLI command.

  • group_name – If specified, the CLI command will belong to a group. When calling a command which belongs to a group, it must be prefixed with the group_name. For example python group_name command_name.

  • command_name – By default, the name of the CLI command will be the same as the function or coroutine which is being called. You can override this here.

  • aliases – The command can also be accessed using these aliases.

run(solo: bool = False)

Run the CLI.


solo – By default, a command name must be given when running the CLI, for example python command_name. In some situations, you may only have a single command registered with the CLI, so passing in the command name is redundant. If solo=True, you can omit the command name i.e. python, and Targ will automatically call the single registered command.