Subcommand aliases

Aliases are alternative names for subcommands. They are often used to define “shortcuts”, e.g. i for install.


The usage of this feature is pretty straightforward: just use the aliases parameter exposed by Cloup command decorators.
def cli():
    """A package installer."""

@cli.command(aliases=['i', 'add'])
def install(pkg: str):
    """Install a package."""
    print('install', pkg)

# Aliases works even if cls is not a Cloup command class
@cli.command(aliases=['uni', 'rm'], cls=click.Command)
def uninstall(pkg: str):
    """Uninstall a package."""
    print('uninstall', pkg)


It’s worth noting that the aliases argument is exposed by all command decorators, not just Group.command and (used in the example above). This is possible because aliases are stored in the subcommand, so a Group can get them from the added command itself.

Help output of the group

By default, aliases are not shown in the “Commands” section(s) of the Group. If you want to show them, you can set show_subcommand_aliases=True as in the example above. This argument is also available as a context setting. With show_subcommand_aliases=True the --help output is:

Usage: cli [OPTIONS] COMMAND [ARGS]...

  A package installer.

  --help  Show this message and exit.

  install (i, add)     Install a package.
  uninstall (uni, rm)  Uninstall a package.

Customizing the format of the first column

If you ever feel the need, you can easily customize the format of the first column overriding the method Group.format_subcommand_name(). My suggestion is to copy the default implementation and modify it.

Help output of the subcommand


Aliases are shown only in the --help output of subcommands that extends cloup.Command. So, normal click.Command won’t do it.

Usage: cli install [OPTIONS] PKG
Aliases: i, add

  Install a package.

  --help  Show this message and exit.

This is possible because aliases are stored in the subcommand itself, precisely in the aliases attribute. Cloup commands declare this attribute and accept it as a parameter. For all other type of commands, Cloup uses monkey-patching to add this attribute.