Skip to content
Back to top
View this page

# Subcommand aliases

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

## Usage

The usage of this feature is pretty straightforward: just use the `aliases` parameter exposed by Cloup command decorators.

    @cloup.group(show_subcommand_aliases=True)
    def cli():
        """A package installer."""
        pass

    @cli.command(aliases=['i', 'add'])
    @cloup.argument('pkg')
    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)
    @cloup.argument('pkg')
    def uninstall(pkg: str):
        """Uninstall a package."""
        print('uninstall', pkg)

Note

It’s worth noting that the `aliases` argument is exposed by all command decorators, not just `Group.command` and `Group.group` (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.

    Options:
      --help  Show this message and exit.

    Commands:
      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

Attention

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.

    Options:
      --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.