cyclopts

enum.Flag (and enum.IntFlag) are treated as collections of boolean flags. You can provide multiple flags via the CLI to combine them.

Behavior:

• Case-insensitive name lookup.
• Underscores in names become hyphens in the CLI.
• You can pass multiple flags as positional arguments or as specific options (e.g., --permissions.write).

To expose flags directly as individual booleans (e.g., --read instead of --permissions.read), use Namespace Flattening.

from cyclopts import App
from enum import Flag, auto

app = App()

class Permission(Flag):
    READ = auto()
    WRITE = auto()
    EXECUTE = auto()

@app.default
def default(permissions: Permission = Permission.READ):
    print(f"Permissions: {permissions}")

app()

Boolean coercion depends on how the parameter is used:

1. As a Keyword (Flag): Booleans act as flags that take no parameters.
   • --my-flag sets the value to True.
   • --no-my-flag sets the value to False (controlled by Parameter.negative).
2. As a Positional Argument: Cyclopts performs a case-insensitive lookup against specific allowed values. It is stricter than standard Python bool() casting.
   • True-like: "yes", "y", "1", "true", "t".
   • False-like: "no", "n", "0", "false", "f".
   • Any other value (including 2) will raise a CoercionError.
3. As a Keyword with assignment (--flag=value): Uses the same positional argument rules as above.

from cyclopts import App

app = App()

@app.command
def foo(my_flag: bool):
    print(my_flag)

app()

Cyclopts supports using classically defined user classes and several dataclass-like libraries as command parameters. This allows you to group related arguments into a single object. Supported libraries include:

• attrs
• dataclass
• NamedTuple
• pydantic (Note: For pydantic classes, Cyclopts relies on Pydantic's own coercion engine rather than performing internal conversions)
• TypedDict

When using these classes, Cyclopts enables subkey parsing via dot-notation (e.g., --user.name) or positional assignment.

from cyclopts import App
from dataclasses import dataclass
from typing import Literal

app = App()

@dataclass
class User:
   name: str
   age: int
   region: Literal["us", "ca"] = "us"

@app.default
def main(user: User):
   print(user)

app()

While Cyclopts and Typer handle most type-hints similarly, there are key differences in how they process specific types:

• enum.Enum: Cyclopts performs lookups in the reverse direction compared to Typer. For terse choice options, typing.Literal is often preferred in Cyclopts.
• typing.Union: Unlike Typer, Cyclopts supports type unions.

The Sphinx directive automatically generates RST reference labels for all commands. This allows you to link to specific commands from anywhere in your documentation using the :ref: role.

The anchor format is cyclopts-{app-name}-{command-path}.

Examples:

• Root application myapp $\rightarrow$ cyclopts-myapp
• Subcommand deploy $\rightarrow$ cyclopts-myapp-deploy
• Nested subcommand production under deploy $\rightarrow$ cyclopts-myapp-deploy-production

See :ref:`cyclopts-myapp-deploy` for deployment options.

Cyclopts is designed to address specific limitations found in the Typer library. Key differences include:

• Function Independence: Unlike older versions of Typer that relied on proxy default values (making decorated functions difficult to use without Typer), Cyclopts leverages modern Python type hints (like Annotated) to ensure decorated command functions remain easy to use as standard Python functions.
• Parsing Control: While Typer is built on top of Click, which can create ambiguity between Typer-specific features and Click-specific features, Cyclopts uses its own internal parsing strategy. This provides complete control over the parsing process and avoids the overhead or confusion of the Click dependency.

When using lazy loading, the import path must point to the real Python identifier. You can use the name parameter to decouple the CLI command name from the Python function name.

Example mapping:

• Python function list_users $\rightarrow$ CLI command list via name="list".
• Python function delete $\rightarrow$ CLI command remove via name="remove".

from cyclopts import App

user_app = App(name="user")

# Function name: "list_users"
# CLI command name: "list"
user_app.command("myapp.commands.users:list_users", name="list")

# Function name: "delete"
# CLI command name: "remove"
user_app.command("myapp.commands.users:delete", name="remove")

When using Union or Optional types, Cyclopts attempts to coerce the input by iterating through the types in the union left-to-right. It stops at the first type that successfully parses the input.

• None type hints are ignored during this process.
• Optional[T] is treated as Union[T, None].