Skip to main content

Option groups and subcommand help sections for pallets/click

Project description


PyPI Package Travis-CI Build Status Coverage Status

cloup (click + group) extends pallets/click to add option groups and the possibility of organizing the subcommands of a Group in multiple help sections.

Currently, this package only affects how the command help is formatted, it doesn’t allow to specify constraints on option groups. Look at click-option-group if you want that. Nonetheless, constraints would be a very easy addition and may be added soon.


To install the last release:

pip install cloup


cloup uses semantic versioning. I’ll release v1.0 when I’m satisfied with API and features but cloup is already usable, just make sure you specify a compatible version number in your list of requirements if you decide to use it, e.g.:


Patch releases are guaranteed to be backwards compatible (even before v1.0).

Option groups

You can define option groups in two ways or “styles”: I’ll call them “nested style” and “flat style”. The full code for the examples shown below can also be found in examples/

Flat style

In “flat style”, you first define your option groups and then call the option() method on them. Don’t reuse OptionGroup objects in multiple commands.

input_grp = OptionGroup('Input options', help='This is a very useful description of the group')
output_grp = OptionGroup('Output options')

@cloup.command('clouptest', align_option_groups=True)
@input_grp.option('-o', '--one', help='1st input option')
@input_grp.option('--two', help='2nd input option')
@input_grp.option('--three', help='3rd input option')
@output_grp.option('--four / --no-four', help='1st output option')
@output_grp.option('--five', help='2nd output option')
@output_grp.option('--six', help='3rd output option')
@option('--seven', help='first uncategorized option', type=click.Choice('yes no ask'.split()))
@option('--height', help='second uncategorized option')
def cli_flat(**kwargs):
    """ A CLI that does nothing. """

Subcommand sections

See the full example code here.

# {Definitions of subcommands are omitted}'git')
def git():
    return 0

group.section() creates a new GroupSection object, adds it to "group" and returns it.

In the help, sections are shown in the same order they are added.
Commands in each sections are shown in the same order they are listed, unless
you pass the argument "sorted=True".
git.section('Start a working area (see also: git help tutorial)',
git.section('Work on the current change (see also: git help everyday)',

# The following commands will be added to the "default section" (a sorted GroupSection)
git.add_command(cloup.command('fake-2', help='Fake command #2')(f))
git.add_command(cloup.command('fake-1', help='Fake command #1')(f))

The help will be:

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

  --help  Show this message and exit.

Start a working area (see also: git help tutorial):
  clone            Clone a repository into a new directory
  init             Create an empty Git repository or reinitialize an...

Work on the current change (see also: git help everyday):
  rm               Remove files from the working tree and from the index
  sparse-checkout  Initialize and modify the sparse-checkout
  mv               Move or rename a file, a directory, or a symlink

Other commands:
  fake-1           Fake command #1
  fake-2           Fake command #2

Though I think using _.section() is the cleanest way to define sections, there are alternatives.

One is to pass a list of GroupSection objects to

    GroupSection('Start a working area (see also: git help tutorial)',
                 git_clone, git_init),
    GroupSection('Work on the current change (see also: git help everyday)',
                 git_rm, git_sparse_checkout, git_mv)
]'git', sections=SECTIONS)
def git():
    return 0

Others are:

  • git.add_section(section) to add an existing GroupSection object
  • git.add_command(cmd, name, section, ...); the section must NOT contain the command
  • @git.command(cmd, name, section, ...), specifying section.

Note: individual commands don’t know the section they belong to. Neither cloup.Command nor @cloup.command() accept a “section” argument.


For implementing option groups, I started from the idea of @chrisjsewell presented in this comment.

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.


0.3.0 (2020-03-26)

  • Backward incompatible API changes
    • option_groups decorator now takes options as positional arguments *options;
    • Group.section decorator now takes sections as positional arguments *sections;
    • align_sections_help was renamed to align_sections;
    • GroupSection.__init__() sorted_ argument was renamed to sorted.
  • Additional signature for option_group: you can pass the help argument as 2nd positional argument.
  • Aligned option groups (option align_option_groups with default True).
  • More refactoring and testing.

0.2.0 (2020-03-11)

  • Rename CloupCommand and CloupGroup resp. to just Command and Group
  • [Feature] Add possibility of organizing subcommands of a cloup.Group in multiple help sections
  • Various code improvements

0.1.0 (2020-02-25)

  • First release on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for cloup, version 0.3.0
Filename, size File type Python version Upload date Hashes
Filename, size cloup-0.3.0-py2.py3-none-any.whl (10.2 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size cloup-0.3.0.tar.gz (19.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page