3.0.0 (December 7, 2025)

Summary

cmd2 now has a dependency on rich for rich text and pretty formatting in the terminal. Previously, cmd2 had a large amount of custom code for this purpose that predated the existence of rich. This opens the door to even more beautiful cmd2 applications. To get the most out of the new capabilities, we encourage you to spend a little bit of time reading the rich documentation.

Details

• Breaking Changes

  • Refactored and modernized styling and utility modules:
    • Removed the legacy table_creator.py module in favor of rich tables (see the rich_tables.py example for more info)
    • Moved all string-related functions from utils.py to a new string_utils.py module
      • Removed redundant string from some of the names so quote_string is now just quote and quote_string_if_needed is now quote_if_needed
    • Consolidated all string styling functions from ansi.py into string_utils.py
    • Replaced all text style enums from ansi.py with modern rich styles
    • Renamed ansi.py to terminal_utils.py to better reflect its purpose
  • Dropped support for Python 3.9. cmd2 now requires Python 3.10 or later
  • Replaced Settable.get_value() and Settable.set_value() methods with a more Pythonic value property
  • Removed redundant setting of a parser's prog value in the with_argparser() decorator, as this is now handled centrally in Cmd._build_parser()
  • The auto_load_commands argument to cmd2.Cmd.__init__ now defaults to False
  • argparse_custom module breaking changes:
    • descriptive_header: str replaced with descriptive_headers: Sequence[str | rich.Column]
      • Applies to parameter name when adding an argument to a parser as well as set_descriptive_headers and get_descriptive_headers
    • CompletionItem.description: str changed to
      CompletionItem.descriptive_data: Sequence[str | rich.Column]
  • decorators module breaking changes:
    • _set_parser_prog renamed to set_parser_prog (without the leading underscore) and moved to argparse_custom module
  • Renamed history --output_file to --output-file to follow common command-line practices

• Enhancements

  • Enhanced all print methods (poutput(), perror(), ppaged(), etc.) to natively render rich objects, enabling beautiful and complex output
  • Simplified the process for setting a custom parser for cmd2's built-in commands. See the custom_parser.py example for an updated guide
  • Introduced Cmd.macro_arg_complete() for tab-completing macro arguments, with default path completion that can be easily customized
  • Added colors.py and styles.py to provide easy access to rich color names and manage cmd2-specific style definitions using StrEnum (see the colors.py example for a demonstration of all colors available to your cmd2 application)
  • Added ability to create a custom theme for a cmd2 application using rich_utils.set_theme (see the rich_theme.py example for more info)
  • Consolidated multiple redundant examples into a few more comprehensive ones, see:
    • argparse_example.py
    • command_sets.py
    • getting_started.py
  • Optimized performance of terminal fixup during command finalization by replacing stty sane with termios.tcsetattr

• Bug Fixes

  • Fixed a redirection bug where cmd2 could unintentionally overwrite an application's sys.stdout

• Migration Aids - these will help you iteratively migrate to cmd2 3.x in stages

  • Published new cmd2-ansi module which is a backport of the cmd2.ansi module present in cmd2 2.7.0
  • Published new cmd2-table module which is a backport of the cmd2.table_creator module present in cmd2 2.7.0