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.