v4.0.0

Compare Source

Cyclopts v4 represents a big feature update that makes it a no-compromise CLI python framework.

While Cyclopts v4 has a few breaking changes that generally make applications cleaner/terser/more intuitive, most shouldn't severely impact applications in the wild. This section lists the changes from most impactful to least.

Breaking Features / Breaking Changes / Migration

• The default help/version formatting has been changed from RestructuredText to Markdown.

  • To keep old behavior, set App(help_format="restructuredtext").

• Default behavior of App.__call__ and App.run_async return value has changed. By default, these methods do not return and now perform a sys.exit. This ensures that scripts and installed applications have consistent exit code behavior. Previously, a script might have had a different exit code compared to an equivalent installed package. This behavior can be controlled via the new attribute App.result_action.

  • To replicate the old behavior, set result_action="return_value" in your root app.

    app = App(result_action="return_value")

• New App-inheritance mechanism/priorities. For most users this will have no impact, but pay attention if you use Meta Apps.

  • Previously, meta-apps were treated as mostly independent. They now inherit configurations from their parent App.
  • The execution path through the App tree may now be different from the inheritance path. Meta App parents are higher up the inheritance tree than meta-apps. I.e., app.meta inherits from app.
  • See #​497 for discussion.

• Dropped Python 3.9 support. Python 3.9 EOL is October 31, 2025.

• On the help page, the root application name falls back to the script name (instead of the registered @app.default command name).

• If a dataclass-like parameter is annotated with Parameter(name="*"), and all of its attributes are optional, but the parameter itself is not optional, a ValueError will now be raised. The value in the function signature must have a default value like None. See discussion in #​519.

• InvalidCommandError has been renamed UnknownCommandError for consistency.

• Errors are now printed to stderr instead of stdout. Uses the new App.error_console.

  • If you want the old behavior (printing errors to stdout), set error_console to a console writing to stdout:

    from rich.console import Console
    app = App(error_console=Console())

• All Parameter arguments except name (the only positional parameter) are now keyword-only.

• If only nameless Groups are assigned to a Parameter, the default Argument/Parameter group is still also applied. This is most convenient when applying a validator without impacting the help page.

Features

Pure "value added" features.

• Lazy loading - Commands can now be registered using import paths (e.g., "myapp.commands.users:create"), which defers module imports until the command is executed. This dramatically improves CLI startup time for applications with many commands or heavy dependencies.

  from cyclopts import App
  
  app = App(name="myapp")
  user_app = App(name="user")

Module only imported when command is executed

user_app.command("myapp.commands.users:create")
app.command(user_app)

* Shell Completion (supports bash, zsh, fish). Enable with `app.register_install_completion_command()`, then users can install via `myapp --install-completion`.
* Standalone python scripts can have dynamic shell completion via the new `cyclopts run` CLI command.
* Help page customization via `help_formatter` parameter on `App` and `Group`.
* Create fully custom formatters by implementing the `HelpFormatter` protocol.
* Built-in formatters: `DefaultFormatter` (Rich-based with colors/borders) and `PlainFormatter` (accessibility-focused plain text).
* New `cyclopts` CLI tool.
* `cyclopts run` - Execute a python script with dynamic shell-completion.
* `cyclopts generate-docs` - Generates documentation in a variety of formats (markdown, restructuredtext, html).
  * Example: `cyclopts generate-docs myscript.py -o docs.md`
* Sphinx Extension for automatically generating CLI documentation from your Cyclopts App.
* Use the `.. cyclopts:: mypackage.cli:app` directive in your RST files.
* New `App` attributes; many of these were available as `App.__call__` parameters, but now they can also be directly set on `App` and are inherited as expected:
* `print_error` - Whether Cyclopts should print the rich-formatted error when a `CycloptsError` is encountered. True by default.
* `exit_on_error` - If there is an error parsing/coercing the CLI tokens, invoke `sys.exit(1)`. True by default.
* `help_on_error` - If there is an error parsing/coercing the CLI tokens, print out the help-page for the parsed application. False by default.
* `verbose` - Populate `CycloptsError` exception strings with more information intended for developers. False by default.
* flatten subapp's subcommands if named `"*"`. by @​BrianPugh in https://github.com/BrianPugh/cyclopts/pull/611
* Add support for `enum.Flag` and `enum.IntFlag`.
* Add support for `datetime.date` type by @​PerchunPak in https://github.com/BrianPugh/cyclopts/pull/601
* Add `cyclopts.config.Dict` config class for in-memory configuration sources. Add new keyword argument `source` to config objects. by @​BrianPugh in https://github.com/BrianPugh/cyclopts/pull/599
* `App.console` now always resolves to a `console` and respects the app-hierarchy. If a console is explicitly assigned, that console will always be used. This makes it easier to access a `console` object within commands.
* Improved parsing of JSON strings from the CLI. Can now handle `list[CustomClass]` if each element is supplied as a JSON string.
* Optimized "happy execution path" performance.
* If `App.sort_key` or `Group.sort_key` are **generators**, Cyclopts automatically invokes `next` on them immediately.
* This allows for streamlined lexical ordering of commands using `itertools.count`:

  ```python
  from itertools import count
  from cyclopts import App, Group

  counter = count()

  @​app.command(group=Group("Commands", sort_key=counter))
  def first():
      pass

  @​app.command(group=Group("Commands", sort_key=counter))
  def second():
      pass
  ```

#### Bug Fixes

* Fixed empty iterables handling within Pydantic models.
* Allow for 0 arguments for iterables (e.g., `list[int]`) when `consume_multiple=True`.
* Fixed incorrect parsing of very large integers.
* Do not parse `help_flags` after `end_of_options_delimiter` by @​BrianPugh in https://github.com/BrianPugh/cyclopts/pull/609

#### Internal / Developer

* Migrated internal project manager from Poetry to uv.

v3.24.0

Compare Source

What's Changed

• introduce App.run_async, an asyncronous equivalent to App.__call__. This allows users to await Cyclopts within an async context (e.g. inside an async meta app). by @​BrianPugh in https://github.com/BrianPugh/cyclopts/pull/539
• Allow async App.version handler by @​gerlero @​BrianPugh in https://github.com/BrianPugh/cyclopts/pull/540

New Contributors

• @​gerlero made their first contribution in https://github.com/BrianPugh/cyclopts/pull/540

Full Changelog: BrianPugh/cyclopts@v3.23.1...v3.24.0

v3.23.1

Compare Source

Bug Fixes

• negative_iterable with an empty string shouldn't appear in the help screen by @​nachocab in https://github.com/BrianPugh/cyclopts/pull/530

Documentation

• Improve contributing docs and .gitignore by @​nachocab in https://github.com/BrianPugh/cyclopts/pull/531

Full Changelog: BrianPugh/cyclopts@v3.23.0...v3.23.1

v3.23.0

Compare Source

Features

• NonExistent* convenience types by @​BrianPugh in https://github.com/BrianPugh/cyclopts/pull/522

Bug Fixes

• When performing command-similarity search, do not recommend commands that have show=False. by @​BrianPugh in https://github.com/BrianPugh/cyclopts/pull/521

Documentation

• Improve consume_multiple documentation by @​nachocab in https://github.com/BrianPugh/cyclopts/pull/517

New Contributors

• @​nachocab made their first contribution in https://github.com/BrianPugh/cyclopts/pull/517

Full Changelog: BrianPugh/cyclopts@v3.22.5...v3.23.0