4.1.0 (July 7, 2026)

• Breaking Changes
  • Renamed the bottom_toolbar argument in Cmd.__init__() to enable_bottom_toolbar. It is also now strictly an __init__ parameter and not an instance attribute.
  • complete_in_thread is now strictly an __init__ parameter and not an instance attribute of Cmd.
  • get_rprompt() is now only called if the enable_rprompt argument in Cmd.__init__() is set to True.
• Bug Fixes
  • Fixed type hinting so that methods decorated with with_annotated no longer trigger spurious mypy errors and preserve their original signature.
  • Fixed cmd2 bypassing NO_COLOR and allow_style when setting prompt-toolkit's color depth.
• Enhancements
  • New cmd2.Cmd parameters
    • complete_in_thread: (boolean) if True, then completion will run in a separate thread. If False then completion runs in the main thread and causes it to block if slow. Defaults to True.
    • refresh_interval: (float) How often, in seconds, to automatically refresh the UI. Defaults to 0.0. This is used for bottom toolbars and right prompts which have dynamic content needing to be refreshed at regular intervals and not just when a key is pressed.
  • Improved getting_started.py example
    • Shows how to properly and safely use a background thread to update the bottom toolbar with dynamic content
    • Demonstrates how to use the @with_argparser and @with_argument_block decorators for parsing command arguments
• Experimental features
  • @with_annotated now supports frozenset[T] collection parameters, alongside the existing list[T], set[T], and tuple[T, ...] collection types.
  • @with_annotated mutually exclusive groups now accept a title/description to render the group as a titled help section (argparse's one supported nesting, a mutex inside an argument group), declared in one place with no paired groups= entry.
  • @with_annotated now validates groups / mutually_exclusive_groups specs eagerly at decoration time, so a misconfigured group (a member that names no parameter, a parameter placed in two groups, a mutex group spanning or partially overlapping argument groups, a titled section declared in two places, or Group(required=True) on a plain group) hard-fails when the class is defined instead of being deferred to first command use where the error was swallowed. The checks read parameter names only, so forward-referenced annotations still decorate cleanly.
  • Argument/Option accept a new allow_unknown_entry flag for Enum parameters. When set, a command-line token matched by neither a member value nor name is routed through the enum's own _missing_ hook, so an enum can resolve aliases, alternate spellings, or special keywords. A token that _missing_ declines (returns None) is still rejected.
  • @with_annotated now supports a union of Enum subclasses (e.g. EnumA | EnumB). Each member keeps its own converter and a token resolves to the first member that accepts it, so when two members share a representation the earlier one in the union wins. A member whose _missing_ raises on a token declines it (the next member is still tried) rather than aborting the union, and a merged "choose from ..." error is raised only when every member declines. Unions containing a Literal or any non-Enum member are still rejected as ambiguous.
  • Argument/Option accept new converter and preprocess hooks for custom string conversion, giving @with_annotated parity with a hand-built add_argument(type=...) (a raw type= in the metadata is still rejected). converter is a Callable[[str], Any] that replaces the inferred type= converter; because it owns the conversion, the annotation may be any type (an otherwise unsupported type like datetime, or an otherwise-ambiguous multi-member union like int | str, becomes legal) and the inferred choices/completer are dropped. preprocess is a Callable[[str], str] that runs before the inferred converter, transforming the raw token while keeping the inferred type=/choices/completer (e.g. preprocess=str.lower on an Enum). The two are mutually exclusive on one parameter and neither may be combined with a value-less action.
  • @with_annotated now supports reusable argument blocks: a parameter typed with a @dataclass that subclasses the new cmd2.ArgumentBlock trait expands each field into a flat command-line argument, and the parsed values are reconstructed into a dataclass instance passed to the command, letting several commands reuse the same fields without duplication. See the annotated documentation.
  • A command can share an argument block with its subcommands via cmd2_base_args / cmd2_parent_args parameters, passing parent-level options down without redeclaring them.