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).