Cyclopts

Cyclopts is a modern, intuitive command-line interface (CLI) framework for Python that provides an efficient developer experience through advanced type hinting support, automatic help generation from docstrings, and extensible customization options. The library enables developers to quickly create CLI applications using a terse, intuitive syntax that fully supports all builtin Python types and user-specified types including Pydantic models, dataclasses, and Attrs.

Package Information

• Package Name: cyclopts
• Language: Python
• Installation: pip install cyclopts
• Minimum Python Version: 3.9
• Documentation: https://cyclopts.readthedocs.io

Core Imports

import cyclopts

Common patterns for building CLI applications:

from cyclopts import App, run
from cyclopts import Parameter, Argument

For configuration and advanced features:

from cyclopts import config, types, validators
from cyclopts import Group, Token

Basic Usage

from cyclopts import run

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

if __name__ == "__main__":
    run(hello)

from cyclopts import App

app = App()

@app.command
def add(x: int, y: int):
    """Add two numbers."""
    print(x + y)

@app.default
def main():
    """Main command when no subcommand specified."""
    print("Use 'add' command to add numbers")

if __name__ == "__main__":
    app()

Architecture

Cyclopts follows a modular architecture centered around these key components:

• App: The main application class that manages commands, parsing, and execution
• Arguments & Parameters: Configuration objects that define how command-line inputs are handled
• Tokens: Immutable representations of user input that track source and parsing context
• Groups: Organizational structures for commands and parameters in help display
• Converters & Validators: Extensible type conversion and validation system
• Configuration System: File-based configuration loading from JSON, TOML, YAML, and environment variables

This design provides maximum flexibility while maintaining an intuitive API that leverages Python's type system for automatic CLI generation.

Capabilities

Core Application Framework

The foundation of Cyclopts CLI applications, providing the App class for command registration, argument parsing, and execution flow control.

class App:
    def __init__(self, **kwargs): ...
    def command(self, func: Callable = None, *, name: str = None) -> Callable: ...
    def default(self, func: Callable = None) -> Callable: ...
    def parse_args(self, tokens: list[str] = None) -> Any: ...
    def __call__(self, tokens: list[str] = None) -> Any: ...

def run(func: Callable, **kwargs) -> Any: ...

Core Application Framework

Argument and Parameter Configuration

Fine-grained control over command-line argument behavior, validation, and presentation through Argument, Parameter, and related configuration classes.

class Argument:
    def __init__(self, **kwargs): ...

class ArgumentCollection(list):
    def __init__(self, *args): ...

class Parameter:
    def __init__(self, **kwargs): ...

Arguments and Parameters

Type System and Validation

Comprehensive type conversion system with pre-built validated types and custom validation support for robust CLI input handling.

def convert(type_, tokens: list[Token]) -> Any: ...

# Pre-built validated types from cyclopts.types
PositiveInt = Annotated[int, ...]
ExistingFile = Annotated[Path, ...]
Email = Annotated[str, ...]

Type System and Validation

Configuration and File Loading

File-based configuration loading system supporting JSON, TOML, YAML formats and environment variable integration.

from cyclopts.config import Json, Toml, Yaml, Env

class Json:
    def __init__(self, file: Path): ...

class Toml:
    def __init__(self, file: Path): ...

Configuration System

Advanced Features

Extended functionality including interactive editing, token manipulation, custom dispatching, and help system customization.

def edit(text: str = "", **kwargs) -> str: ...
def env_var_split(value: str, type_: type) -> list[str]: ...

class Token:
    keyword: str
    value: str
    source: str

Advanced Features

Exception Handling

Comprehensive exception hierarchy for precise error handling and debugging in CLI applications.

class CycloptsError(Exception): ...
class ValidationError(CycloptsError): ...
class MissingArgumentError(CycloptsError): ...

Exception Handling