Cyclopts

4.10.1 · active · verified Sun Mar 29

Cyclopts is a modern, easy-to-use command-line interface (CLI) framework built on Python type hints, offering an intuitive and efficient developer experience. It provides advanced type hinting support, rich help page generation from docstrings, and extensive customization options for parsing and launching. The library is actively maintained, currently at version 4.10.1, with frequent updates and ongoing development towards version 5.0.

Warnings

breaking Major version 5.x (currently in alpha) is expected to introduce breaking changes. While specific details are not yet fully documented, major version bumps typically involve API alterations. Always review the official migration guide when upgrading to a new major version.
Fix: Consult the official Cyclopts v5 migration guide (when available) and update code to reflect new API patterns and behaviors.
gotcha Migrating from Typer: `Argument` and `Option` from `typer` are replaced by `cyclopts.Parameter`. The handling of default actions, callbacks, `Enum` lookups, and `Union` types differs. Cyclopts natively supports `Union` types, unlike Typer.
Fix: Replace `typer.Argument`/`typer.Option` with `cyclopts.Parameter`. Re-evaluate default command logic and how `Enum`/`Union` types are handled.
gotcha Parameter Resolution Order: When multiple `Parameter` annotations are applied (e.g., at the function, group, or app level), explicitly set attributes in `Annotated[..., Parameter()]` for a specific function parameter have the highest priority.
Fix: Be aware of the resolution hierarchy: function-level annotations > group `default_parameter` > app `default_parameter`. Override specific behaviors at the highest-priority level needed.
gotcha Implicit Type Coercion: If a function parameter lacks an explicit type hint, Cyclopts will attempt to infer its type from a non-None default value. If no default is provided, it defaults to `str`. This can lead to unexpected parsing if not explicitly hinted.
Fix: Always provide explicit type hints (e.g., `value: int`) for function parameters to ensure correct type coercion and prevent unexpected `str` parsing.
gotcha Lazy Loading `--help` Behavior (pre-v4.8.0): Prior to version 4.8.0, running `--help` on a parent command would eagerly import and resolve *all* lazy child commands. This negated the startup-time benefits of lazy loading.
Fix: Upgrade to Cyclopts v4.8.0 or later. For lazy commands, provide the `help=` argument at registration time (e.g., `app.command('module:command_func', help='Description')`) to display descriptions without triggering imports.

Install

pip install cyclopts Install stable version

Imports

App
```
from cyclopts import App
```
Parameter
```
from cyclopts import Parameter
```
Often used with `typing.Annotated` for detailed parameter configuration.
run
```
from cyclopts import run
```
A terser API for simple applications with a single command.

Quickstart

This basic example demonstrates creating an `App` instance, registering a default command using the `@app.default` decorator, and defining parameters with type hints. Docstrings are automatically used to generate help messages. The `app()` call parses command-line arguments and executes the corresponding function.

from cyclopts import App

app = App()

@app.default
def main(name: str, count: int = 1):
    """Greets the given name(s).

    Parameters
    ----------
    name: str
        The name to greet.
    count: int
        Number of times to greet.
    """
    for _ in range(count):
        print(f"Hello, {name}!")

if __name__ == "__main__":
    # Example usage: python your_script.py World --count 3
    # Or: python your_script.py --help
    app()

view raw JSON →