cyclopts 4.0.0

v4.0.0

on Python PyPI

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 #611

• Add support for enum.Flag and enum.IntFlag.

• Add support for datetime.date type by @PerchunPak in #601

• Add cyclopts.config.Dict config class for in-memory configuration sources. Add new keyword argument source to config objects. by @BrianPugh in #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:

    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 #609

Internal / Developer

• Migrated internal project manager from Poetry to uv.