4.0.0 (June 5, 2026)

[tleonhardt]

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 developers to parameterize it with their specific cmd2.Cmd subclass (e.g.,class MyCommandSet(CommandSet[MyApp]):). This provides full type hints and IDE autocompletion for self._cmd without needing to override and cast the property.
  • Added traceback_kwargs attribute to allow customization of Rich-based tracebacks.
  • Added HelpFormatterRenderable protocol and HelpContent type alias to support context-aware help content in argparse.
  • The print() function available in a pyscript writes to self.stdout and respects the allow_style setting. It also supports printing Rich objects.
  • Added Cmd2ArgumentParser.output_to() context manager to temporarily set the output stream during argparse operations. This is helpful for directing output for functions like parse_args(), which default to sys.stdout and lack a file argument.
  • Added ability to customize prompt-toolkit completion menu colors by overriding the following fields in the cmd2 theme:
    • Cmd2Style.COMPLETION_MENU - Base style for the entire completion menu container (sets the background)
    • Cmd2Style.COMPLETION_MENU_COMPLETION -Style for an individual, non-selected completion item
    • Cmd2Style.COMPLETION_MENU_CURRENT - Style for the currently selected completion item
    • Cmd2Style.COMPLETION_MENU_META - Style for "meta" information shown alongside a completion
    • Cmd2Style.COMPLETION_MENU_META_CURRENT- Style for meta info of current item
  • Updated set command to consolidate its confirmation output into a single, colorized line. The confirmation now uses pfeedback(), allowing it to be silenced when the quiet settable is enabled.
  • alias and macro subcommands for create and delete now output their non-essential success case output using pfeedback
• Experimental features
  • New @with_annotated decorator, a type-hint-driven alternative to @with_argparse that builds the parser automatically from a command's signature (positional/option inference, enum/literal/path/collection handling, subcommands, groups, mutex). See the annotated_example.py example for demonstration of usage.
    • This feature allows declaring cmd2 command parameters using type hints using syntax essentially identical to that used by Typer
    • You use declarative syntax to define the arguments a command takes and the @with_annotated decorator builds an argparse parser for you

---

This discussion was created from the release 4.0.0 (June 5, 2026).

[tleonhardt]

One interesting side effect of the change to using prompt-toolkit under the hood for providing completions is that it is using a background thread for doing this to prevent blocking the interactive CLI. Hence, your previously single-threaded apps are now defacto multi-threaded apps with the background thread used for completion managed in a transparent way that you shouldn't ever need to worry about.

This may result in some surprising behavior for a small percentage of users. In particular, this is likely to impact anyone using Python's built-in sqlite3 module in a manner where you are doing sqlite queries to provide completion options. If you fall into this group, please see Issue #1680 for solutions.

[neoniobium]

Thanks for the great release. Migration went smoothly and I did not encounter any bugs yet.

I have a question regarding the experimental with_annotated decorator. The typer-like approach looks clean to a and I would like to use it. However I am not sure want 'experimental' constitutes: Will this feature only pron to change or is there also a change that it will be removed completely in a future release?

[neoniobium]

Sounds great! Breaking changes are fine with me. I will attempt migrating to the with_annotated approach and will provide feedback on my experience with the new decorator.

[neoniobium]

I migrated part of my application and, as promised, have some feedback:

I like this a lot. It is very clean, makes good use of type checking, and reduces the total number of lines by a decent amount. I especially like the well-implemented out-of-the-box completion based on the annotations. The basic usage works great.

I have some questions and comments:

1. with_annotated does not work in conjunction with the staticmethod decorator. This is not a big deal for me, but I think this is unexpected behavior. (with_annotated and with_argparse decorators do not work with staticmethod #1683)

2. Is there an intended way to define a mutually exclusive group inside a normal argument group? I think this is supported by argparse, while nested groups and groups inside mutually exclusive groups are not supported since Python 3.11. argparse (Intended way to define a mutually exclusive group inside a normal argument group with with_annotated #1687)

3. A Union of Enums and/or Literals is currently not supported. I think this would be useful. (Support Union of Enum and/or Literal in annotations for with_annotated decorator #1686)

4. Currently frozenset is not a supported type annotation. I think this would be useful. (with_annotated should support frozenset #1685)

5. When using the argparse approach, the type argument of add_argument can be used for non-basic type conversion (see example). I would like a dedicated argument for this purpose. (Use with_annotated decorator with custom types for allow easy type conversion #1688)

6. To avoid redundant code, it would be great to have some kind of template functionality for argument blocks that appear in more than one method. With the with_argparse decorator this is straightforward to do by writing a function that modifies a parser. I could imagine using TypedDict in conjunction with **kwargs for this purpose. Another approach would be simply attaching a predefined parser to the one generated with with_annotated. (Template functionality for argument blocks using with_annotaed decorator #1689)

7. mypy complains about the decorated functions. I think this can be fixed using ParamSpec instead of the ellipsis-notation. (Mypy complains about method decorated with with_annotated decorator #1684)

...: error: Type of decorated function contains type "Any" ("Callable[..., Any]")  [misc]
        def decorated_example(

8. Is there an intended way to modify, add, or pass arguments from a parent parser to a subparser? For example:

parser --option {subparser-A, subparser-B}

I would like to use option (defined on the parent parser) as an argument of subparser-A or subparser-B without generating the argument on either subparser. The ns_provider argument might be useful for this. (#1690)

[tleonhardt]

@neoniobium Thanks for your detailed feedback!

For anything that seems like a bug like the @with_annotated decorator not working in conjunction with another decorator such as @staticmethod or mypy complaining about types when used, please create an Issue with as much detail as possible for how to reproduce.

Similarly for things that seem like missing but desirable features, please also create an Issue (one for each) with as much detail as possible describing how you envision the intended feature working.

Also, if you know how to tackle any of it, please feel free to submit PRs. Same goes if you have ideas for how to improve the documentation.

@KelvinChung2000 is the one who contributed the @with_annotated feature set and wrote all of the code behind it. Pinging you Kelvin in case you have any thoughts on the above feedback.

[KelvinChung2000]

I will look into it

[neoniobium]

Ok, each point has a separate issue now. Please let me know if anything is unclear.