Pre-release

This release is a pre-release and may not be stable for production use.

Python compat

Documentation: https://cyclopts.readthedocs.io

Source Code: https://github.com/BrianPugh/cyclopts

Cyclopts is a modern, easy-to-use command-line interface (CLI) framework that aims to provide an intuitive & efficient developer experience.

Why Cyclopts?

Intuitive API: Quickly write CLI applications using a terse, intuitive syntax.
Advanced Type Hinting: Full support of all builtin types and even user-specified (yes, including Pydantic, Dataclasses, and Attrs).
Rich Help Generation: Automatically generates beautiful help pages from docstrings and other contextual data.
Extendable: Easily customize converters, validators, token parsing, and application launching.

Installation

Cyclopts requires Python >=3.11; to install Cyclopts, run:

pip install cyclopts

Quick Start

Import cyclopts.run() and give it a function to run.

from cyclopts import run

def foo(loops: int):
    for i in range(loops):
        print(f"Looping! {i}")

run(foo)

Execute the script from the command line:

$ python start.py 3
Looping! 0
Looping! 1
Looping! 2

When you need more control:

Create an application using cyclopts.App.
Register commands with the command decorator.
Register a default function with the default decorator.

from cyclopts import App

app = App()

@app.command
def foo(loops: int):
    for i in range(loops):
        print(f"Looping! {i}")

@app.default
def default_action():
    print("Hello world! This runs when no command is specified.")

app()

Execute the script from the command line:

$ python demo.py
Hello world! This runs when no command is specified.

$ python demo.py foo 3
Looping! 0
Looping! 1
Looping! 2

With just a few additional lines of code, we have a full-featured CLI app. See the docs for more advanced usage.

Compared to Typer

Cyclopts is what you thought Typer was. Cyclopts includes information from docstrings, supports more complex types (even Unions!), and includes proper validation support. See the documentation for a complete Typer comparison.

Consider the following short 29-line Cyclopts application:

import cyclopts
from typing import Literal

app = cyclopts.App()

@app.command
def deploy(
    env: Literal["dev", "staging", "prod"],
    replicas: int | Literal["default", "performance"] = "default",
):
    """Deploy code to an environment.

    Parameters
    ----------
    env
        Environment to deploy to.
    replicas
        Number of workers to spin up.
    """
    if replicas == "default":
        replicas = 10
    elif replicas == "performance":
        replicas = 20

    print(f"Deploying to {env} with {replicas} replicas.")


if __name__ == "__main__":
    app()

$ my-script deploy --help
Usage: my-script.py deploy [ARGS] [OPTIONS]

Deploy code to an environment.

╭─ Parameters ────────────────────────────────────────────────────────────────────────────────────╮
│ *  ENV --env            Environment to deploy to. [choices: dev, staging, prod] [required]      │
│    REPLICAS --replicas  Number of workers to spin up. [choices: default, performance] [default: │
│                         default]                                                                │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯

$ my-script deploy staging
Deploying to staging with 10 replicas.

$ my-script deploy staging 7
Deploying to staging with 7 replicas.

$ my-script deploy staging performance
Deploying to staging with 20 replicas.

$ my-script deploy nonexistent-env
╭─ Error ────────────────────────────────────────────────────────────────────────────────────────────╮
│ Error converting value "nonexistent-env" to typing.Literal['dev', 'staging', 'prod'] for "--env".  │
╰────────────────────────────────────────────────────────────────────────────────────────────────────╯

$ my-script --version
0.0.0

In its current state, this application would be impossible to implement in Typer; Typer does not support the union type-hint of replicas. However, let's see how close we can get with Typer (41-lines):

import typer
from typing import Annotated, Literal

app = typer.Typer()

def replica_parser(value: str):
    if value == "default":
        return 10
    elif value == "performance":
        return 20
    else:
        return int(value)

def _version_callback(value: bool):
    if value:
        print("0.0.0")
        raise typer.Exit()

@app.callback()
def callback(
    version: Annotated[
        bool | None, typer.Option("--version", callback=_version_callback)
    ] = None,
):
    pass

@app.command(help="Deploy code to an environment.")
def deploy(
    env: Annotated[Literal["dev", "staging", "prod"], typer.Argument(help="Environment to deploy to.")],
    replicas: Annotated[
        int,
        typer.Argument(
            parser=replica_parser,
            help="Number of workers to spin up.",
        ),
    ] = replica_parser("default"),
):
    print(f"Deploying to {env} with {replicas} replicas.")

if __name__ == "__main__":
    app()

$ my-script deploy --help

 Usage: my-script deploy [OPTIONS] {env}:<dev|staging|prod> [replicas]

 Deploy code to an environment.

╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────╮
│ *    env           <dev|staging|prod>  Environment to deploy to. [required]                     │
│      replicas      <replica_parser>    Number of workers to spin up. [default: 10]              │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                     │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯

$ my-script deploy staging
Deploying to staging with 10 replicas.

$ my-script deploy staging 7
Deploying to staging with 7 replicas.

$ my-script deploy staging performance
Deploying to staging with 20 replicas.

$ my-script deploy nonexistent-env
Usage: my-script deploy [OPTIONS] {env}:<dev|staging|prod> [replicas]
Try 'my-script deploy --help' for help.
╭─ Error ─────────────────────────────────────────────────────────────────────────────────────────╮
│ Invalid value for 'env': 'nonexistent-env' is not one of 'dev', 'staging', 'prod'.              │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯

$ my-script --version
0.0.0

The Typer implementation is 41 lines long, while the Cyclopts implementation is just 29 (29% shorter!). Not only is the Cyclopts implementation significantly shorter, but the code is easier to read. Since Typer does not support Unions, the choices for replicas could not be displayed on the help page. Cyclopts is much more terse, much more readable, and much more intuitive to use.

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, coding standards, and how to submit a pull request.

Release files for cyclopts 5.0.0b2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cyclopts 5.0.0b2
File	Size	Uploaded
cyclopts-5.0.0b2.tar.gz	235.9 kB	Sep 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cyclopts 5.0.0b2
File	Interpreter	ABI	Platform	Reset
cyclopts-5.0.0b2-py3-none-any.whl 277.4 kB Sep 11, 2026	Python 3	none	any	Details

Total release size: 513.3 kB

Release files / cyclopts-5.0.0b2.tar.gz

Download URL	cyclopts-5.0.0b2.tar.gz
Size	235.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`830c46298aabc8e9ee3234b94ca6375dd63c198a0c6d7604acab4f646f1ef758`
BLAKE2b-256 checksum How to use checksums	`5b92c1a3b45b9670cd87cdde65a9583d105bf88cd7275f34cd12ef8afaff3099`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/BrianPugh/cyclopts
Publishing commit: github.com/BrianPugh/cyclopts/tree/64e68fb0d4e40576a945ef1e2024e060a58b3fe2

Workflow

Publishing configuration: github.com/BrianPugh/cyclopts/blob/64e68fb0d4e40576a945ef1e2024e060a58b3fe2/.github/workflows/deploy.yaml
Publishing logs: github.com/BrianPugh/cyclopts/actions/runs/34545471684/attempts/1

Artifact

Subject: cyclopts-5.0.0b2.tar.gz
SHA-256 checksum: 830c46298aabc8e9ee3234b94ca6375dd63c198a0c6d7604acab4f646f1ef758 Verifying attestations

Release files / cyclopts-5.0.0b2-py3-none-any.whl

Download URL	cyclopts-5.0.0b2-py3-none-any.whl
Size	277.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`dee8fefbddbc6c47006055f1eeb5c6020910f55bbb3e6439350ec1cc7c3c9266`
BLAKE2b-256 checksum How to use checksums	`9bc4a89e361d8fceea305c939f13bc8b91af5b243c5bc5d9c2b028d909d7033d`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/BrianPugh/cyclopts
Publishing commit: github.com/BrianPugh/cyclopts/tree/64e68fb0d4e40576a945ef1e2024e060a58b3fe2

Workflow

Publishing configuration: github.com/BrianPugh/cyclopts/blob/64e68fb0d4e40576a945ef1e2024e060a58b3fe2/.github/workflows/deploy.yaml
Publishing logs: github.com/BrianPugh/cyclopts/actions/runs/34545471684/attempts/1

Artifact

Subject: cyclopts-5.0.0b2-py3-none-any.whl
SHA-256 checksum: dee8fefbddbc6c47006055f1eeb5c6020910f55bbb3e6439350ec1cc7c3c9266 Verifying attestations