cloup

Cloup — originally from “Click + option groups” — enriches Click with several features that make it more expressive and configurable:

option groups and an (optional) help section for positional arguments
constraints, like mutually_exclusive, that can be applied to option groups or to any group of parameters, even conditionally
subcommand aliases
subcommands sections, i.e. the possibility of organizing the subcommands of a Group in multiple help sections
a themeable HelpFormatter that:
- has more parameters for adjusting widths and spacing, which can be provided at the context and command level
- use a different layout when the terminal width is below a certain threshold in order to improve readability
suggestions like “did you mean <subcommand>?” when you mistype a subcommand.

Moreover, Cloup improves on IDE support providing decorators with detailed type hints and adding the static methods Context.settings() and HelpFormatter.settings() for creating dictionaries of settings.

Cloup is statically type-checked with MyPy in strict mode and extensively tested against multiple versions of Python with nearly 100% coverage.

A simple example

from cloup import (
    HelpFormatter, HelpTheme, Style,
    command, option, option_group
)
from cloup.constraints import RequireAtLeast, mutually_exclusive

# Check the docs for all available arguments of HelpFormatter and HelpTheme.
formatter_settings = HelpFormatter.settings(
    theme=HelpTheme(
        invoked_command=Style(fg='bright_yellow'),
        heading=Style(fg='bright_white', bold=True),
        constraint=Style(fg='magenta'),
        col1=Style(fg='bright_yellow'),
    )
)

# In a multi-command app, you can pass formatter_settings as part
# of your context_settings so that they are propagated to subcommands.
@command(formatter_settings=formatter_settings)
@option_group(
    "Cool options",
    option('--foo', help='This text should describe the option --foo.'),
    option('--bar', help='This text should describe the option --bar.'),
    constraint=mutually_exclusive,
)
@option_group(
    "Other cool options",
    "This is the optional description of this option group.",
    option('--pippo', help='This text should describe the option --pippo.'),
    option('--pluto', help='This text should describe the option --pluto.'),
    constraint=RequireAtLeast(1),
)
def cmd(**kwargs):
    """This is the command description."""
    pass

if __name__ == '__main__':
    cmd(prog_name='invoked-command')

If you don’t provide --pippo or --pluto:

Usage: invoked-command [OPTIONS]
Try 'invoked-command --help' for help.

Error: at least 1 of the following parameters must be set:
  --pippo
  --pluto

This simple example just scratches the surface. Read more in the documentation (links below).

Metadata

Release files for cloup 3.0.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cloup 3.0.9
File	Size	Uploaded
cloup-3.0.9.tar.gz	229.9 kB	Apr 4, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cloup 3.0.9
File	Interpreter	ABI	Platform	Reset
cloup-3.0.9-py2.py3-none-any.whl 54.7 kB Apr 4, 2026	Python 2, Python 3	none	any	Details

Total release size: 284.6 kB

Release files / cloup-3.0.9.tar.gz

Download URL	cloup-3.0.9.tar.gz
Size	229.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`519f524d3c64040e49a0866b5fc0bfd6af3eac0d3d6a4b2b50b33ab0247db2d7`
BLAKE2b-256 checksum How to use checksums	`f9647f0a66021ff81d51859c66adc13f3c71f0306c2f8dfb9877a0694cbada05`
Upload date	Apr 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Release files / cloup-3.0.9-py2.py3-none-any.whl

Download URL	cloup-3.0.9-py2.py3-none-any.whl
Size	54.7 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`c761ef4e975454335d50c0e1eb83595a932735aac06e8955b3ced774bc62ae7b`
BLAKE2b-256 checksum How to use checksums	`7715435bb5a24e3a2dc8c26afedab0c6f0cf4291c66fb99509c168c38eb81135`
Upload date	Apr 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`