cloup

What it is and what it does

Cloup is a Click extension that adds structured organization and validation to command-line interfaces. It lets you group related options, apply constraints like mutual exclusivity or minimum-required counts, organize subcommands into sections, and customize help output with themes and colors. The package is built on top of Click and adds decorators with detailed type hints, making it easier to write complex CLIs with better IDE support and validation.

The library is actively maintained, supports Python 3.9 through 3.13, and has no known security vulnerabilities. It depends only on Click and typing_extensions, keeping installation lightweight. The codebase is statically type-checked with MyPy and extensively tested, making it suitable for production CLI applications where you need more control over option organization and user-facing validation messages.

Use it for:

• Organize related CLI options into labeled groups with shared constraints like mutual exclusivity or minimum-required selections
• Build multi-level command hierarchies with subcommands organized into logical sections in the help output
• Apply conditional parameter validation (e.g., require at least N of a group, or enforce mutual exclusivity) without manual checking
• Customize help text appearance with themed colors and styles, including responsive layouts for narrow terminals
• Provide "did you mean?" suggestions when users mistype subcommand names

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Cloup extends Click with option groups, parameter constraints, subcommand sections, themeable help formatting, and subcommand aliases to build more expressive command-line interfaces.

Yes. Cloup is a lightweight, actively maintained extension that solves real CLI organization and validation problems. If you're building a Click-based CLI with multiple options or subcommands, Cloup's option groups and constraints eliminate boilerplate validation code and improve help readability. The permissive license, low dependency footprint, and current Python version support make it a safe, practical choice.

Install

cloup on PyPI

pip install cloup

uv add cloup

poetry add cloup

Installing cloup

Before you install

Low install friction with only two runtime dependencies (click and typing_extensions). Actively maintained with a release 80 days ago and recent commits; supports Python 3.9 through 3.13.

License in practice

BSD 3-Clause is permissive; you can use, modify, and distribute this package with minimal restrictions, provided you include the license notice.

Quickstart

pip install cloup

from cloup import command, option_group, option
from cloup.constraints import mutually_exclusive

@command()
@option_group(
    "Options",
    option('--foo'),
    option('--bar'),
    constraint=mutually_exclusive,
)
def cmd(**kwargs):
    pass

if __name__ == '__main__':
    cmd()

Verify before relying

• Whether the 100% test coverage claim and MyPy strict-mode checking are maintained in the current release
• Performance impact of constraint validation on large option sets or deeply nested command hierarchies

Package facts

Evidence: cloup-3.1.0-py2.py3-none-any.whl

Keywords: CLI, click, argument groups, option groups, constraints, help colors, help themes, help styles

Tags

More Application Frameworks packages