# 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](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)
example for the simple use case of statically setting the prompt.

## Continuation Prompt

When a user types a [Multiline Command](./multiline_commands.md) 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](https://github.com/python-cmd2/cmd2/blob/main/examples/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](./hooks.md#application-lifecycle-hooks) such as a
[Postcommand hook](./hooks.md#postcommand-hooks). See
[python_scripting.py](https://github.com/python-cmd2/cmd2/blob/main/examples/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.
1. **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](https://github.com/python-cmd2/cmd2/blob/main/examples/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 `enable_bottom_toolbar=True` in the [cmd2.Cmd.__init__][] constructor:

```py
class App(cmd2.Cmd):
    def __init__(self):
        super().__init__(enable_bottom_toolbar=True)
```

### Customizing Toolbar Content

You can customize the content of the toolbar by overriding the [cmd2.Cmd.get_bottom_toolbar][]
method.

```py
    from prompt_toolkit.formatted_text import AnyFormattedText

    def get_bottom_toolbar(self) -> AnyFormattedText:
        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 set `refresh_interval` in the [cmd2.Cmd.__init__][] constructor to a value
greater than 0.0.

```py
class App(cmd2.Cmd):
    def __init__(self):
        super().__init__(refresh_interval=0.5)
```

See the
[getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)
example for a demonstration of this technique.
