Cleo

Cleo is a Python library for creating beautiful and testable command-line interfaces. You define each command as a class with declared arguments and options and a handle method, register it on an Application, and Cleo handles parsing, help generation, styled output and error display. It powers the CLI of Poetry, among other projects.

Beyond argument parsing, Cleo provides styled and colored output, progress bars, tables, interactive prompts, and a command tester that lets you assert on a command’s output and exit code in unit tests, which is why testability is a first-class design goal.

What You Get

• Class-based commands with declarative arguments, options and auto-generated help.
• Styled, colored terminal output plus tables, progress bars and interactive prompts.
• A command tester for asserting on output and exit codes in unit tests.
• An Application runner that handles parsing, dispatch and error rendering.

Common Use Cases

• Building a polished multi-command CLI tool in Python.
• Writing testable command handlers with assertions on output and exit code.
• Rendering progress bars, tables and colored output in terminal apps.

Under The Hood

Architecture

Cleo is structured as an Application that registers Command objects and drives an IO abstraction; under src/cleo/ the io layer models input (argv parsing into arguments/options) and styled output, commands define the handler base class, and formatters, ui, descriptors and testers provide styling, widgets, help rendering and in-process test drivers respectively.

Tech Stack

Pure Python packaged with Poetry (pyproject.toml, poetry.lock), typed with a py.typed marker; minimal runtime dependencies, tested with pytest under tests/, and self-hosted as the CLI engine behind Poetry.

Code Quality

A well-organized, fully typed codebase with clear module boundaries between IO, commands, formatting and testers, backed by a solid test suite; the project is undergoing a 3.0 rewrite noted in the README, so the 2.x line is stable and maintenance-focused.

API Design

Excellent developer experience: commands are declarative classes, the IO object makes styled output and prompts easy, and the built-in testers make CLIs genuinely unit-testable - a differentiator over bare argparse - with a gentle learning curve for common cases.