Skip to content

# 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 getting_started.py 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 getting_started.py 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 python_scripting.py for an example of dynamically updating the prompt.

## Asynchronous Feedback

`cmd2` provides a function to deliver asynchronous feedback to the user without interfering with the command line. This allows feedback to be provided while the user is still entering text at the prompt.

- cmd2.Cmd.add_alert

### Asynchronous Feedback Mechanisms

Alerts can interact with the CLI in two ways:

1. Message Printing: It can print a message directly above the current prompt line.
2. Prompt Updates: It can dynamically replace the text of the active prompt to reflect changing state.

Note

To ensure the user interface remains accurate, a prompt update is ignored if the alert was created before the current prompt was rendered. This prevents older alerts from overwriting a newer prompt, though the alert's message will still be printed.

### Terminal Window Management

`cmd2` also provides a function to change the title of the terminal window.

- cmd2.Cmd.set_window_title

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

## Bottom Toolbar

`cmd2` supports an optional, persistent bottom toolbar that is always visible at the bottom of the terminal window while the application is idle and waiting for input.

### Enabling the Toolbar

To enable the toolbar, set `bottom_toolbar=True` in the cmd2.Cmd.init constructor:

    class App(cmd2.Cmd):
        def __init__(self):
            super().__init__(bottom_toolbar=True)

### Customizing Toolbar Content

You can customize the content of the toolbar by overriding the cmd2.Cmd.get_bottom_toolbar method. This method should return either a string or a list of `(style, text)` tuples for formatted text.

        def get_bottom_toolbar(self) -> list[str | tuple[str, str]] | None:
            return [
                ('ansigreen', 'My Application Name'),
                ('', ' - '),
                ('ansiyellow', 'Current Status: Idle'),
            ]

### Refreshing the Toolbar

Since the toolbar is rendered by `prompt-toolkit` as part of the prompt, it is naturally redrawn whenever the prompt is refreshed. If you want the toolbar to update automatically (for example, to display a clock), you can use a background thread to call `app.invalidate()` periodically.

See the getting_started.py example for a demonstration of this technique.