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.
pip install cycloptsVerified import paths — ran on the pinned version, not inferred.
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.
Consult the official Cyclopts v5 migration guide (when available) and update code to reflect new API patterns and behaviors.
Replace `typer.Argument`/`typer.Option` with `cyclopts.Parameter`. Re-evaluate default command logic and how `Enum`/`Union` types are handled.
Be aware of the resolution hierarchy: function-level annotations > group `default_parameter` > app `default_parameter`. Override specific behaviors at the highest-priority level needed.
Always provide explicit type hints (e.g., `value: int`) for function parameters to ensure correct type coercion and prevent unexpected `str` parsing.
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.Ensure all required parameters are supplied with their corresponding argument values when invoking a command. Define a default value for parameters if they should be optional.
Adjust the input value to comply with the expected validation criteria or modify the validator function if the criteria are incorrect. For example, if using `cyclopts.validators.Number.range()`, ensure the input falls within the specified range.
Ensure the command name provided on the command line exactly matches a registered command or check for typos. If the command should be available, verify it has been correctly registered with `@app.command` or that it is the default command using `@app.default`.
Modify the command-line input to specify the parameter only once, or adjust the `Parameter` definition in your code to `allow_repeating=True` if the argument is intended to accept multiple values that form a list or similar collection.
Verify that the import path (e.g., `nonexistent.module` and `func`) is correct and that the module is accessible within your Python environment. Ensure there are no typos in the module path or the function/App name specified after the colon.