4.0.0b1 (2026-03-03)

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
  • 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_header.
  • CompletionItem.descriptive_data is now called CompletionItem.table_row.
  • 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.completion_hint
    • Cmd.formatted_completions -> Completions.completion_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.
• 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
  • New settables:
    • max_column_completion_results: (int) the maximum number of completion results to
      display in a single column

3.4.0 (March 3, 2026)

• Enhancements

  • Moved cmd2-specific printing logic from Cmd.print_to() into Cmd2BaseConsole.print() and Cmd2BaseConsole.log(). This removes need to pass a console object to Cmd.print_to().
  • Addressed a bug in rich.console.Console where complex renderables (like Table and Rule) may not receive formatting settings passed to console.print() and console.log().

• Breaking Changes

  • Renamed the destination parameter of Cmd.print_to() back to file since you can no longer pass in a console.

3.3.0 (March 1, 2026)

• Enhancements

  • Added ability to pass a console object to Cmd.print_to(). This provides support for things
    like wrapping a print_to() call in a console.status() or console.capture() context
    manager.

• Breaking Changes

  • Renamed the file parameter of Cmd.print_to() to destination to support file-like objects
    and console objects.
  • Cmd2BaseConsole(file) argument is now a keyword-only argument to be consistent with the
    rich.console.Console class.

3.2.2 (February 21, 2026)

• Bug Fixes
  • Updated rich_utils.ANSI_STYLE_SEQUENCE_RE to only match ANSI SGR (Select Graphic Rendition) sequences for text styling. It previously also matched DEC Private Mode sequences.

3.2.1 (February 21, 2026)

• Bug Fixes
  • The async_alert and async_prompt_update methods of cmd2.Cmd now respect the current
    value of the allow_style settable
    • If allow_style is NEVER, all style-related ANSI escape codes will be stripped to ensure plain text
      output

3.2.0 (February 5, 2026)

• Bug Fixes

  • Fixed incompatibilities with Python 3.14.3.

• Potentially Breaking Changes

  • To avoid future incompatibilities with argparse, we removed most of our overridden help functions. This should not break an application, but it could affect unit tests which parse help text.

3.1.3 (February 3, 2026)

• Bug Fixes
  • Fixed issue where delimiter_complete() could cause more matches than display matches
  • Fixed issue where CommandSet registration did not respect disabled categories

3.1.2 (January 26, 2026)

• Bug Fixes
  • Fixed missing typing-extensions dependency for Python 3.10

3.1.1 (January 26, 2026)

• Bug Fixes
  • Fixed bug where rich-argparse was not coloring cmd2's custom nargs formatting

3.1.0 (December 25, 2025)

• Potentially Breaking Changes
  • cmd2 no longer has a dependency on cmd and cmd2.Cmd no longer inherits from cmd.Cmd
    • We don't think this should impact users, but there is theoretically a possibility
    • This opens the door for more impactful changes in the next major release