4.2.4 (September 8, 2026)

What's Changed

• uv run does its own sync of the project env with default groups by @tleonhardt in #1746
• Add aggregation jobs to maxtrix workflows by @tleonhardt in #1747
• Keep the right prompt out of the committed prompt frame by @tleonhardt in #1749
• Write redirected and piped output as UTF-8, and stop the suite inheriting colour settings by @tleonhardt in #1753
• Fix ty errors present in version 0.0.79 which came out yesterday by @tleonhardt in #1754

Full Changelog: 4.2.3...4.2.4

4.2.3 (September 2, 2026)

What's Changed

• Fix ty unresolved-attribute warnings and add mypy back by @tleonhardt in #1737
• Update ruff to version 0.16.5 by @tleonhardt in #1738
• Bump github/codeql-action from 4.37.8 to 4.37.9 by @dependabot[bot] in #1740
• Update readme by @tleonhardt in #1739

Full Changelog: 4.2.2...4.2.3

4.2.2 (August 25, 2026)

• Documentation Improvements
  • Improved documentation in attempt at making some recommended best-practices more discoverable
  • Fixed the broken cmd_as_argument example

4.2.1 (August 22, 2026)

• Enhancements
  • Added bracketed paste support so multiple pasted commands execute sequentially and multiline commands continue as expected.
• Bug Fixes
  • Enabled Ctrl-Z suspension at the prompt

4.2.0 (August 6, 2026)

• Enhancements
  • @with_annotated argument groups can now contain an ArgumentBlock's arguments. A Group member names a command-line argument, and a block expands into one argument per field, so its fields are named: Group("host", "port").
• Breaking Changes
  • A Group member now names an argument rather than a parameter. The two differ only for an ArgumentBlock parameter, which is expanded away and has no argument of its own: Group("conn") now raises ValueError pointing at the block's fields. It previously produced an empty argument group in groups= and a KeyError in mutually_exclusive_groups=.
  • Whether a Group member exists is now validated when the parser is built rather than at decoration time, because a block's field names cannot be known without resolving its type hint, and resolving hints eagerly would break forward-referenced annotations. A typo in a member name still raises ValueError, but on first use of that command rather than at class definition. The spec-shape rules (a member listed twice, a member in two groups, required=True on a plain group, the mutex nesting rules) are unaffected and still hard-fail at decoration time.
• Bug Fixes
  • Fixed @with_annotated(base_command=True) not listing its subcommands under the positional arguments section of the parent command's --help, unlike argparse and Cmd2ArgumentParser. They were placed in an untitled section of their own instead. Passing subcommand_title or subcommand_description still gives the subcommands a dedicated section (#1715).
  • Fix @with_annotated decorator so using ArgumentBlock works with groups (#1718).
  • Fixed bug where already sorted choices_provider results were being re-sorted (#1727).

4.1.2 (July 16, 2026)

What's Changed

• Updated getting_started.py example to remove multi-line command usage by @tleonhardt in #1713
• [Settable] description argument can now be rich text by @neoniobium in #1712
• Removed redundant ipython import which slowed application startup time by @kmvanbrunt in #1717

New Contributors

• @neoniobium made their first contribution in #1712

Full Changelog: 4.1.1...4.1.2

4.1.1 (July 9, 2026)

What's Changed

• Fixed mypy 2.2.0 failures by @tleonhardt in #1709
• Added ability to use Rich renderables as alert messages. by @kmvanbrunt in #1710

Full Changelog: 4.1.0...4.1.1

4.1.0 (July 7, 2026)

• Breaking Changes
  • Renamed the bottom_toolbar argument in Cmd.__init__() to enable_bottom_toolbar. It is also now strictly an __init__ parameter and not an instance attribute.
  • complete_in_thread is now strictly an __init__ parameter and not an instance attribute of Cmd.
  • get_rprompt() is now only called if the enable_rprompt argument in Cmd.__init__() is set to True.
• Bug Fixes
  • Fixed type hinting so that methods decorated with with_annotated no longer trigger spurious mypy errors and preserve their original signature.
  • Fixed cmd2 bypassing NO_COLOR and allow_style when setting prompt-toolkit's color depth.
• Enhancements
  • New cmd2.Cmd parameters
    • complete_in_thread: (boolean) if True, then completion will run in a separate thread. If False then completion runs in the main thread and causes it to block if slow. Defaults to True.
    • refresh_interval: (float) How often, in seconds, to automatically refresh the UI. Defaults to 0.0. This is used for bottom toolbars and right prompts which have dynamic content needing to be refreshed at regular intervals and not just when a key is pressed.
  • Improved getting_started.py example
    • Shows how to properly and safely use a background thread to update the bottom toolbar with dynamic content
    • Demonstrates how to use the @with_argparser and @with_argument_block decorators for parsing command arguments
• Experimental features
  • @with_annotated now supports frozenset[T] collection parameters, alongside the existing list[T], set[T], and tuple[T, ...] collection types.
  • @with_annotated mutually exclusive groups now accept a title/description to render the group as a titled help section (argparse's one supported nesting, a mutex inside an argument group), declared in one place with no paired groups= entry.
  • @with_annotated now validates groups / mutually_exclusive_groups specs eagerly at decoration time, so a misconfigured group (a member that names no parameter, a parameter placed in two groups, a mutex group spanning or partially overlapping argument groups, a titled section declared in two places, or Group(required=True) on a plain group) hard-fails when the class is defined instead of being deferred to first command use where the error was swallowed. The checks read parameter names only, so forward-referenced annotations still decorate cleanly.
  • Argument/Option accept a new allow_unknown_entry flag for Enum parameters. When set, a command-line token matched by neither a member value nor name is routed through the enum's own _missing_ hook, so an enum can resolve aliases, alternate spellings, or special keywords. A token that _missing_ declines (returns None) is still rejected.
  • @with_annotated now supports a union of Enum subclasses (e.g. EnumA | EnumB). Each member keeps its own converter and a token resolves to the first member that accepts it, so when two members share a representation the earlier one in the union wins. A member whose _missing_ raises on a token declines it (the next member is still tried) rather than aborting the union, and a merged "choose from ..." error is raised only when every member declines. Unions containing a Literal or any non-Enum member are still rejected as ambiguous.
  • Argument/Option accept new converter and preprocess hooks for custom string conversion, giving @with_annotated parity with a hand-built add_argument(type=...) (a raw type= in the metadata is still rejected). converter is a Callable[[str], Any] that replaces the inferred type= converter; because it owns the conversion, the annotation may be any type (an otherwise unsupported type like datetime, or an otherwise-ambiguous multi-member union like int | str, becomes legal) and the inferred choices/completer are dropped. preprocess is a Callable[[str], str] that runs before the inferred converter, transforming the raw token while keeping the inferred type=/choices/completer (e.g. preprocess=str.lower on an Enum). The two are mutually exclusive on one parameter and neither may be combined with a value-less action.
  • @with_annotated now supports reusable argument blocks: a parameter typed with a @dataclass that subclasses the new cmd2.ArgumentBlock trait expands each field into a flat command-line argument, and the parsed values are reconstructed into a dataclass instance passed to the command, letting several commands reuse the same fields without duplication. See the annotated documentation.
  • A command can share an argument block with its subcommands via cmd2_base_args / cmd2_parent_args parameters, passing parent-level options down without redeclaring them.

4.0.0 (June 5, 2026)

Summary

cmd2 now has a dependency on prompt-toolkit which serves as a pure-Python cross-platform replacement for GNU Readline. Previously, cmd2 had used different readline dependencies on each Operating System (OS) which was at times a very frustrating developer and user experience due to small inconsistencies in these different readline libraries. Now we have consistent cross-platform support for tab-completion, user terminal input, and history. Additionally, this opens up some cool advanced features such as support for syntax highlighting of user input while typing, auto-suggestions similar to those provided by the fish shell, and the option for a persistent bottom bar that can display realtime status updates while the prompt is displayed.

Details

• Breaking Changes
  • Removed all use of readline built-in module and underlying platform libraries
  • Deleted cmd2.rl_utils module which dealt with importing the proper readline module for each platform and provided utility functions related to readline
  • Added a dependency on prompt-toolkit and a new cmd2.pt_utils module with supporting utilities
  • Dropped support for Python 3.10. cmd2 now requires Python 3.11 or later
  • Removed Transcript Testing feature set along with the history -t option for generating transcript files and the cmd2.transcript module
    • This was an extremely brittle regression testing framework which should never have been built into cmd2
    • We recommend using pytest for unit and integration tests and Robot Framework for acceptance tests. Both of these frameworks can be used to create tests which are far more reliable and less brittle.
  • Async specific: prompt-toolkit starts its own asyncio event loop in every cmd2 application
    • Removed cmd2.Cmd.terminal_lock as it is no longer required to support things like cmd2.Cmd.async_alert
    • Removed cmd2.Cmd.async_refresh_prompt and cmd2.Cmd.need_prompt_refresh as they are no longer needed
  • completer functions must now return a cmd2.Completions object instead of list[str].
  • choices_provider functions must now return a cmd2.Choices object instead of list[str].
  • An argparse argument's descriptive_headers field is now called table_columns.
  • CompletionItem.descriptive_data is now called CompletionItem.table_data.
  • Removed DEFAULT_DESCRIPTIVE_HEADERS. This means you must define table_columns when using CompletionItem.table_data data.
  • Cmd.default_sort_key moved to utils.DEFAULT_STR_SORT_KEY.
  • Moved completion state data, which previously resided in Cmd, into other classes.
    • Cmd.matches_sorted -> Completions.is_sorted and Choices.is_sorted
    • Cmd.completion_hint -> Completions.hint
    • Cmd.formatted_completions -> Completions.table (Now a Rich Table)
    • Cmd.allow_appended_space/allow_closing_quote -> Completions.allow_finalization
  • Removed Cmd.matches_delimited since it's no longer used.
  • Removed flag_based_complete and index_based_complete functions since their functionality is already provided in arpgarse-based completion.
  • Changed Statement.multiline_command from a string to a bool.
  • Made Statement.arg_list a property which generates the list on-demand.
  • Renamed Statement.output to Statement.redirector.
  • Renamed Statement.output_to to Statement.redirect_to.
  • Removed Statement.pipe_to since it can be handled by Statement.redirector and Statement.redirect_to.
  • Changed StatementParser.parse_command_only() to return a PartialStatement object.
  • Renamed Macro.arg_list to Macro.args.
  • Removed terminal_utils.py since prompt-toolkit provides this functionality.
  • Replaced async_alert() and async_update_prompt() with a single function called add_alert(). This new function is thread-safe and does not require you to acquire a mutex before calling it like the previous functions did.
  • Removed Cmd.default_to_shell.
  • Removed Cmd.ruler since cmd2 no longer uses it.
  • All parsers used with cmd2 commands must be an instance of Cmd2ArgumentParser or a child class of it.
  • Renamed set_default_argument_parser_type() to set_default_argument_parser().
  • Renamed set_default_ap_completer_type() to set_default_argparse_completer().
  • Removed set_ap_completer_type() and get_ap_completer_type() since completer_class is now a public member of Cmd2ArgumentParser.
  • Moved set_parser_prog() to Cmd2ArgumentParser.update_prog().
  • Renamed cmd2_handler to cmd2_subcommand_func in the argparse.Namespace for clarity.
  • Removed Cmd2AttributeWrapper class. argparse.Namespace objects passed to command functions now contain direct attributes for cmd2_statement and cmd2_subcommand_func.
  • Renamed cmd2/command_definition.py to cmd2/command_set.py.
  • Removed Cmd.doc_header and the with_default_category decorator. Help categorization is now driven by the DEFAULT_CATEGORY class variable (see Simplified command categorization in the Enhancements section below for details).
  • Removed Cmd.undoc_header since all commands are now considered categorized.
  • Renamed Cmd.cmd_func() to Cmd.get_command_func().
  • cmd2 no longer sets a default title for a subparsers group. If you desire a title, you will need to pass one in like this parser.add_subparsers(title="subcommands"). This is standard argparse behavior.
  • TextGroup now implements HelpFormatterRenderable (see Enhancements section below for more details).
    • Removed formatter_creator parameter from TextGroup.__init__().
    • Removed Cmd2ArgumentParser.create_text_group() method.
  • argparse and Rich integration refactoring:
    • Renamed argparse_custom module to argparse_utils.
    • Moved the following classes from argparse_utils to rich_utils:
      • Cmd2HelpFormatter
      • ArgumentDefaultsCmd2HelpFormatter
      • MetavarTypeCmd2HelpFormatter
      • RawDescriptionCmd2HelpFormatter
      • RawTextCmd2HelpFormatter
      • TextGroup
    • Replaced the global APP_THEME constant in rich_utils.py with get_theme(), reset_theme(), and update_theme() functions in theme.py to support lazy initialization and safer in-place updates of the theme.
  • Renamed Cmd._command_parsers to Cmd.command_parsers.
  • Removed RichPrintKwargs TypedDict in favor of using Mapping[str, Any], allowing for greater flexibility in passing keyword arguments to console.print() calls.
  • Removed always_show_hint settable as it provided a poor user experience with prompt-toolkit
  • cmd2 redirection only captures output directed to self.stdout (e.g., via self.poutput()). Standard print() calls write directly to sys.stdout and are not captured. However, print() calls within pyscripts and the interactive Python shell are treated as command output and sent to self.stdout, allowing them to be captured.
  • Verbose help table descriptions are no longer generated from help function output. The system now relies exclusively on command function docstrings.
  • Removed feedback_to_output settable and changed cmd2.Cmd.pfeedback to always print to self.stdout
  • Removed Cmd.parseline() since it was unused and merely wrapped StatementParser.parse_command_only().
• Enhancements
  • New cmd2.Cmd parameters
    • auto_suggest: (boolean) if True, provide fish shell style auto-suggestions. These are grayed-out hints based on history. User can press right-arrow key to accept the provided suggestion.
    • bottom toolbar: (boolean) if True, present a persistent bottom toolbar capable of displaying realtime status information while the prompt is displayed, see the cmd2.Cmd2.get_bottom_toolbar method that can be overridden as well as the updated getting_started.py example
  • New cmd2.Cmd methods
    • get_bottom_toolbar: populates bottom toolbar if bottom_toolbar is True
    • get_rprompt: override to populate right prompt
    • pre_prompt: hook method that is called before the prompt is displayed, but after
      prompt-toolkit event loop has started
    • read_secret: read secrets like passwords without displaying them to the terminal
    • ppretty: a cmd2-compatible replacement for rich.pretty.pprint()
  • New settables:
    • max_column_completion_results: (int) Maximum number of completion results to display in a single column
    • traceback_show_locals: (bool) Display local variables in tracebacks
  • cmd2.Cmd.select has been revamped to use the choice function from prompt-toolkit when both stdin and stdout are TTYs
  • Add support for Python 3.15 by fixing various bugs related to internal argparse changes
  • Added common_prefix method to cmd2.string_utils module as a replacement for os.path.commonprefix since that is now deprecated in Python 3.15
  • Simplified command categorization:
    • By default, all commands in a class are grouped under its DEFAULT_CATEGORY.
    • Individual commands can still be manually moved using the with_category() decorator.
    • For more details and examples, see the Help documentation and the examples/default_categories.py file.
  • CommandSet is now a generic class, which allows devel...

4.0.0-rc2 (2026-06-04)

What's Changed

• feat: Experimental annotated argparse by @KelvinChung2000 in #1666
• Refactor and standardize argparse-related naming and metadata by @kmvanbrunt in #1670

• Breaking Changes
  • Renamed set_default_argument_parser_type() to set_default_argument_parser().
  • Renamed set_default_ap_completer_type() to set_default_argparse_completer().
  • Renamed cmd2_subcmd_handler to cmd2_subcommand_func in the argparse.Namespace for clarity.

New Contributors

• @KelvinChung2000 made their first contribution in #1666

Full Changelog: 4.0.0-rc1...4.0.0-rc2