Prompt

cmd2 issues a configurable prompt before soliciting user input.

Customizing the Prompt

This prompt can be configured by setting the cmd2.Cmd.prompt instance attribute. This contains the string which should be printed as a prompt for user input. See the Pirate example for the simple use case of statically setting the prompt.

Continuation Prompt

When a user types a Multiline Command it may span more than one line of input. The prompt for the first line of input is specified by the cmd2.Cmd.prompt instance attribute. The prompt for subsequent lines of input is defined by the cmd2.Cmd.continuation_prompt attribute.See the Initialization example for a demonstration of customizing the continuation prompt.

Updating the prompt

If you wish to update the prompt between commands, you can do so using one of the Application Lifecycle Hooks such as a Postcommand hook. See PythonScripting for an example of dynamically updating the prompt.

Asynchronous Feedback

cmd2 provides two functions to provide asynchronous feedback to the user without interfering with the command line. This means the feedback is provided to the user when they are still entering text at the prompt. To use this functionality, the application must be running in a terminal that supports VT100 control characters and readline. Linux, Mac, and Windows 10 and greater all support these.

Cmd.async_alert(alert_msg: str, new_prompt: Optional[str] = None) → None

Display an important message to the user while they are at a command line prompt. To the user it appears as if an alert message is printed above the prompt and their current input text and cursor location is left alone.

IMPORTANT: This function will not print an alert unless it can acquire self.terminal_lock to ensure
a prompt is onscreen. Therefore it is best to acquire the lock before calling this function to guarantee the alert prints and to avoid raising a RuntimeError.
Parameters:
  • alert_msg – the message to display to the user
  • new_prompt – If you also want to change the prompt that is displayed, then include it here. See async_update_prompt() docstring for guidance on updating a prompt.
Raises:

RuntimeError – if called while another thread holds terminal_lock

Cmd.async_update_prompt(new_prompt: str) → None

Update the command line prompt while the user is still typing at it. This is good for alerting the user to system changes dynamically in between commands. For instance you could alter the color of the prompt to indicate a system status or increase a counter to report an event. If you do alter the actual text of the prompt, it is best to keep the prompt the same width as what’s on screen. Otherwise the user’s input text will be shifted and the update will not be seamless.

IMPORTANT: This function will not update the prompt unless it can acquire self.terminal_lock to ensure

a prompt is onscreen. Therefore it is best to acquire the lock before calling this function to guarantee the prompt changes and to avoid raising a RuntimeError.

If user is at a continuation prompt while entering a multiline command, the onscreen prompt will not change. However self.prompt will still be updated and display immediately after the multiline line command completes.

Parameters:new_prompt – what to change the prompt to
Raises:RuntimeError – if called while another thread holds terminal_lock

cmd2 also provides a function to change the title of the terminal window. This feature requires the application be running in a terminal that supports VT100 control characters. Linux, Mac, and Windows 10 and greater all support these.

static Cmd.set_window_title(title: str) → None

Set the terminal window title.

NOTE: This function writes to stderr. Therefore if you call this during a command run by a pyscript,
the string which updates the title will appear in that command’s CommandResult.stderr data.
Parameters:title – the new window title

The easiest way to understand these functions is to see the AsyncPrinting example for a demonstration.