4.0.0b1 (2026-03-03)

[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
  • 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

---

This discussion was created from the release 4.0.0b1 (2026-03-03).