Aliases are alternative names for subcommands. They are often used to
define “shortcuts”, e.g.
The usage of this feature is pretty straightforward: just use the
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)
It’s worth noting that the
aliases argument is exposed by all command
decorators, not just
Group.group (used in the
example above). This is possible because aliases are stored in the subcommand,
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
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.
--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
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
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
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.