Cyclopts

Cyclopts is a modern, easy-to-use command-line interface framework for Python that generates CLIs directly from your function signatures and type hints. You annotate a function’s parameters, register it, and Cyclopts handles argument parsing, type conversion, validation, and help-page generation for you.

Designed as a successor-in-spirit to Typer, Cyclopts leans heavily on Python’s type system, supporting builtin types as well as dataclasses, attrs, and Pydantic models. It automatically produces rich, beautiful help pages from docstrings and offers deep extensibility over converters, validators, token parsing, and application launching.

What You Get

• Automatic CLI generation from function signatures and type hints
• Support for builtin types plus dataclasses, attrs, and Pydantic models as parameters
• Beautiful, Rich-rendered help pages generated from docstrings
• Nested subcommands and command groups for structuring larger CLIs
• Extensible converters, validators, token parsing, and app-launch hooks

Common Use Cases

• Building developer and internal tooling CLIs with minimal boilerplate
• Exposing typed Python functions as command-line commands and subcommands
• Creating CLIs whose arguments map onto structured config objects
• Generating polished, self-documenting help output for command-line apps

Under The Hood

Architecture — Cyclopts centers on the App object (cyclopts/core.py) that holds a command tree and dispatches invocations. When run, it binds CLI tokens to parameters through a pipeline of argument resolution (cyclopts/argument, cyclopts/bind.py, cyclopts/token.py), type conversion (cyclopts/_convert.py, cyclopts/types.py, cyclopts/annotations.py), and validation (cyclopts/validators). Help pages are assembled by the cyclopts/help and cyclopts/panel.py modules using Rich, while configuration loaders (cyclopts/config, cyclopts/loader.py) support pulling defaults from files and environment variables. Shell completion lives under cyclopts/completion.

Tech Stack — Pure Python (requires 3.10+), built with a hatchling/hatch-vcs backend. Runtime dependencies are attrs for internal data modeling, rich and rich-rst for help rendering, and docstring-parser for extracting help text from docstrings. Optional extras add TOML config, YAML config, and trio async support. It ships a py.typed marker for full type-checker support.

Code Quality — The project is very actively maintained with consistent releases, high test coverage tracked on codecov, and an extensive test suite under tests/. The codebase is cleanly modularized by concern — binding, conversion, validation, help, config, completion — and ships type stubs (__init__.pyi) and a Sphinx extension for documentation, reflecting a mature engineering standard.

API Design — The developer experience is a core selling point. A one-liner run(func) handles simple scripts, while the App object plus @app.command scales to complex, nested CLIs. Because parameters come straight from type hints and docstrings, there is little duplicated metadata, and the framework’s rich validators and converters keep advanced customization discoverable. Documentation on Read the Docs is thorough with many worked examples.