Here is a basic example
cmd2 application which demonstrates many
capabilities which you may wish to utilize while initializing the app:
#!/usr/bin/env python3 # coding=utf-8 """A simple example cmd2 application demonstrating the following: 1) Colorizing/stylizing output 2) Using multiline commands 3) Persistent history 4) How to run an initialization script at startup 5) How to group and categorize commands when displaying them in help 6) Opting-in to using the ipy command to run an IPython shell 7) Allowing access to your application in py and ipy 8) Displaying an intro banner upon starting your application 9) Using a custom prompt 10) How to make custom attributes settable at runtime """ import cmd2 from cmd2 import ( Bg, Fg, style, ) class BasicApp(cmd2.Cmd): CUSTOM_CATEGORY = 'My Custom Commands' def __init__(self): super().__init__( multiline_commands=['echo'], persistent_history_file='cmd2_history.dat', startup_script='scripts/startup.txt', include_ipy=True, ) # Prints an intro banner once upon application startup self.intro = style('Welcome to cmd2!', fg=Fg.RED, bg=Bg.WHITE, bold=True) # Show this as the prompt when asking for input self.prompt = 'myapp> ' # Used as prompt for multiline commands after the first line self.continuation_prompt = '... ' # Allow access to your application in py and ipy via self self.self_in_py = True # Set the default category name self.default_category = 'cmd2 Built-in Commands' # Color to output text in with echo command self.foreground_color = Fg.CYAN.name.lower() # Make echo_fg settable at runtime fg_colors = [c.name.lower() for c in Fg] self.add_settable( cmd2.Settable('foreground_color', str, 'Foreground color to use with echo command', self, choices=fg_colors) ) @cmd2.with_category(CUSTOM_CATEGORY) def do_intro(self, _): """Display the intro banner""" self.poutput(self.intro) @cmd2.with_category(CUSTOM_CATEGORY) def do_echo(self, arg): """Example of a multiline command""" fg_color = Fg[self.foreground_color.upper()] self.poutput(style(arg, fg=fg_color)) if __name__ == '__main__': app = BasicApp() app.cmdloop()
Cmd class initializer¶
cmd2.Cmd instance or subclass instance is an interactive CLI application
framework. There is no good reason to instantiate
Cmd itself; rather, it’s
useful as a superclass of a class you define yourself in order to inherit
Cmd’s methods and encapsulate action methods.
Certain things must be initialized within the
__init__() method of your
class derived from
cmd2.Cmd``(all arguments to ``__init__() are optional):
__init__(completekey: str = 'tab', stdin: Optional[TextIO] = None, stdout: Optional[TextIO] = None, *, persistent_history_file: str = '', persistent_history_length: int = 1000, startup_script: str = '', silence_startup_script: bool = False, include_py: bool = False, include_ipy: bool = False, allow_cli_args: bool = True, transcript_files: Optional[List[str]] = None, allow_redirection: bool = True, multiline_commands: Optional[List[str]] = None, terminators: Optional[List[str]] = None, shortcuts: Optional[Dict[str, str]] = None, command_sets: Optional[Iterable[cmd2.command_definition.CommandSet]] = None, auto_load_commands: bool = True) → None
An easy but powerful framework for writing line-oriented command interpreters. Extends Python’s cmd package.
- completekey – readline name of a completion key, default to Tab
- stdin – alternate input file object, if not specified, sys.stdin is used
- stdout – alternate output file object, if not specified, sys.stdout is used
- persistent_history_file – file path to load a persistent cmd2 command history from
- persistent_history_length – max number of history items to write to the persistent history file
- startup_script – file path to a script to execute at startup
- silence_startup_script – if
True, then the startup script’s output will be suppressed. Anything written to stderr will still display.
- include_py – should the “py” command be included for an embedded Python shell
- include_ipy – should the “ipy” command be included for an embedded IPython shell
- allow_cli_args – if
cmd2.Cmd.__init__()will process command line arguments as either commands to be run or, if
--testare given, transcript files to run. This should be set to
Falseif your application parses its own command line arguments.
- transcript_files – pass a list of transcript files to be run on initialization.
This allows running transcript tests when
Truethis parameter is ignored.
- allow_redirection – If
False, prevent output redirection and piping to shell commands. This parameter prevents redirection and piping, but does not alter parsing behavior. A user can still type redirection and piping tokens, and they will be parsed as such but they won’t do anything.
- multiline_commands – list of commands allowed to accept multi-line input
- terminators – list of characters that terminate a command. These are mainly intended for terminating multiline commands, but will also terminate single-line commands. If not supplied, the default is a semicolon. If your app only contains single-line commands and you want terminators to be treated as literals by the parser, then set this to an empty list.
- shortcuts – dictionary containing shortcuts for commands. If not supplied, then defaults to constants.DEFAULT_SHORTCUTS. If you do not want any shortcuts, pass an empty dictionary.
- command_sets – Provide CommandSet instances to load during cmd2 initialization. This allows CommandSets with custom constructor parameters to be loaded. This also allows the a set of CommandSets to be provided when auto_load_commands is set to False
- auto_load_commands – If True, cmd2 will check for all subclasses of CommandSet that are currently loaded by Python and automatically instantiate and register all commands. If False, CommandSets must be manually installed with register_command_set.
Cmd instance attributes¶
cmd2.Cmd class provides a large number of public instance attributes
which allow developers to customize a
cmd2 application further beyond the
options provided by the
Public instance attributes¶
Here are instance attributes of
cmd2.Cmd which developers might wish
- broken_pipe_warning: if non-empty, this string will be displayed if a broken pipe error occurs
- continuation_prompt: used for multiline commands on 2nd+ line of input
- debug: if
Trueshow full stack trace on error (Default:
- default_category: if any command has been categorized, then all other commands that haven’t been categorized will display under this section in the help output.
- default_error: the error that prints when a non-existent command is run
- default_sort_key: the default key for sorting string results. Its default value performs a case-insensitive alphabetical sort.
- default_to_shell: if
Trueattempt to run unrecognized commands as shell commands (Default:
- disabled_commands: commands that have been disabled from use. This is to support commands that are only available during specific states of the application. This dictionary’s keys are the command names and its values are DisabledCommand objects.
- doc_header: Set the header used for the help function’s listing of documented functions
- echo: if
True, each command the user issues will be repeated to the screen before it is executed. This is particularly useful when running scripts. This behavior does not occur when running a command at the prompt. (Default:
- editor: text editor program to use with edit command (e.g.
- exclude_from_history: commands to exclude from the history command
- exit_code: this determines the value returned by
cmdloop()when exiting the application
- feedback_to_output: if
Truesend nonessential output to stdout, if
Falsesend them to stderr (Default:
- help_error: the error that prints when no help information can be found
- hidden_commands: commands to exclude from the help menu and tab completion
- last_result: stores results from the last command run to enable usage of results in a Python script or interactive console. Built-in commands don’t make use of this. It is purely there for user-defined commands and convenience.
- self_in_py: if
Trueallow access to your application in py command via
- macros: dictionary of macro names and their values
- max_completion_items: max number of CompletionItems to display during tab completion (Default: 50)
- pager: sets the pager command used by the
Cmd.ppaged()method for displaying wrapped output using a pager
- pager_chop: sets the pager command used by the
Cmd.ppaged()method for displaying chopped/truncated output using a pager
- py_bridge_name: name by which embedded Python environments and scripts
refer to the
cmd2application by in order to call commands (Default:
- py_locals: dictionary that defines specific variables/functions available in Python shells and scripts (provides more fine-grained control than making everything available with self_in_py)
- quiet: if
Truethen completely suppress nonessential output (Default:
- settable: dictionary that controls which of these instance attributes are settable at runtime using the set command
- timing: if
Truedisplay execution time for each command (Default: