cmd2 Documentation

The cmd2 public API is organized into several specialized modules. To ensure stability, only items explicitly documented in the API reference should be considered part of the public interface. Even if a class, method, or function does not start with an underscore, it may still be private and subject to change if it is not documented in the official API reference.

cmd2 follows Semantic Versioning (SemVer) for all changes to its documented public API.

The cmd2.Cmd class is the primary entry point for building immersive interactive command line applications. By subclassing cmd2.Cmd, you can create a custom command loop that supports advanced features like command completion, command history, and sophisticated argument parsing. To start your application, you typically override the do_ methods for each command you wish to implement and then call the run() method to enter the interactive loop.

import cmd2

class MyApp(cmd2.Cmd):
    def do_hello(self, args):
        """Say hello to the user."""
        self.poutput(f"Hello, {args}!")

if __name__ == '__main__':
    app = MyApp()
    app.cmdloop()

The @with_annotated decorator is an experimental feature that builds an argparse parser automatically from the decorated function's Python type annotations. This eliminates the need for manual add_argument() calls.

Warning: As this is experimental, the API may change in future releases.

When cmd2.Cmd.cmdloop() is called, the following sequence is repeated for every command:

1. Start prompt-toolkit event loop.
2. Call pre_prompt.
3. Output the prompt and accept input.
4. Parse input into a cmd2.Statement object.
5. Postparsing Hooks are called.
6. Redirect output (if requested).
7. Start timer.
8. Precommand Hooks are called.
9. Call precmd (for cmd.Cmd compatibility).
10. Add statement to History.
11. Call do_command (the actual command execution).
12. Postcommand Hooks are called.
13. Call postcmd (for cmd.Cmd compatibility).
14. Stop timer and display elapsed time.
15. Stop output redirection.
16. Command Finalization Hooks are called.

Error Handling: If a hook raises an exception, no further hooks (except command finalization hooks) are called, the command is not executed, and the exception message is displayed to the user.

Command history is enabled by default.

User Interaction:

• Use Control-p (previous) and Control-n (next) to navigate history.
• Use Control-r to search through history.
• These bindings follow Emacs-style conventions provided by the prompt-toolkit library.

Built-in history command: Users can use the history command to:

• View history by number, range, or string/regex search.
• Re-run commands.
• Edit commands in a text editor before execution.
• Save commands and their output to files.

While command methods receive a string, cmd2 actually passes a cmd2.Statement object. This object is a subclass of str that provides access to parsed components of the user input, such as quoted arguments, output redirection, and piping. Using the argv attribute is a common way to handle arguments without manual parsing.

Attributes of a Statement object:

• command: The name of the command called.
• args: The arguments string with output redirection or piping removed (quotes remain).
• command_and_args: The command and arguments string with output redirection or piping removed.
• argv: A list of arguments (like sys.argv), where argv[0] is the command. Quotes are stripped and redirection/piping is removed.
• raw: The full input exactly as typed by the user.
• terminator: The character used to end a multiline command.

When building a cmd2 application, consider the following design principles to ensure a good experience for both users and scripters:

1. Design from the inside out: Implement core logic in low-level class libraries first. This makes the code easier to unit test and keeps the high-level API clean.
2. Respect boundaries: A high-level Python script should interact with the command interface, not directly access low-level class libraries. This maintains encapsulation.
3. Follow the Unix philosophy: Designing small, composable commands gives scripters the most flexibility to build complex workflows.
4. Fail fast: Since cmd2 catches application exceptions, ensure your commands provide clear error messages in stderr so scripters can detect failures using the CommandResult object.

You can annotate a parameter as a Union of multiple Enum subclasses (e.g., Suit | Rank). The parser resolves the token using a first-match-wins strategy: the first member in the Union that accepts the token via its value, name, or _missing_ hook wins.

Important Considerations:

• Order matters: If a token is valid for multiple members, the first one listed in the Union is selected.
• Exclusivity: Only Enum members are supported in the Union. Including Literal or non-Enum types will result in an ambiguity error.
• Collisions: If value sets overlap significantly, consider using typed subcommands instead.

@with_annotated
def do_pick(self, choice: Suit | Rank) -> None:
    if isinstance(choice, Suit):
        self.poutput(f"suit {choice.name}")
    else:
        self.poutput(f"rank {choice.name}")