simple-term-menu

To allow users to select multiple items, pass multi_select=True to the constructor.

Usage:

• Use space or tab to toggle selections.
• Press an accept key to finish. The show() method returns a sorted tuple of indices.
• Use the chosen_menu_entries property to get the actual strings of the selected items.

Configuration:

• multi_select_keys: Custom keys to toggle items (default: " ,tab").
• show_multi_select_hint=True: Shows a hint in the status bar.
• multi_select_select_on_accept=False: If False, the currently highlighted item is NOT automatically added to the selection upon pressing the accept key.
• multi_select_empty_ok=True: Allows returning an empty selection if no items were explicitly selected.
• preselected_entries: An iterable of integers (indices) or strings (matching entry text) to pre-select items on startup.

from simple_term_menu import TerminalMenu

def main():
    terminal_menu = TerminalMenu(
        ["dog", "cat", "mouse", "squirrel"],
        multi_select=True,
        show_multi_select_hint=True,
    )
    # Returns a tuple of indices, e.g., (0, 2)
    menu_entry_indices = terminal_menu.show()
    # Returns a tuple of strings, e.g., ("dog", "mouse")
    print(terminal_menu.chosen_menu_entries)

if __name__ == "__main__":
    main()

You can show a preview of the selected entry by passing a preview_command to the constructor.

Command Formats:

1. Shell Command String: A string where {} is a placeholder for the menu entry. If the entry contains a | separator (e.g., filename|data), the part after the | is passed to the placeholder instead.
2. Python Callable: A function that takes the menu entry string and returns the preview output (can include ANSI color codes).

Preview Settings:

• preview_size: Height of the window as a fraction of terminal height (default: 0.25).
• preview_title: Custom title for the window (default: "preview").
• preview_border=False: Removes the border and the title.

# Example using a Python callable for syntax highlighting
from simple_term_menu import TerminalMenu

def highlight_file(filepath):
    with open(filepath, "r") as f:
        return f.read() # Simplified for example

def main():
    terminal_menu = TerminalMenu(
        ["file1.txt", "file2.txt"],
        preview_command=highlight_file,
        preview_size=0.75
    )
    terminal_menu.show()

if __name__ == "__main__":
    main()

You can customize the visual appearance of the menu by passing tuples of keyword strings to the TerminalMenu constructor.

Accepted Style Keywords:

• Backgrounds: bg_black, bg_blue, bg_cyan, bg_gray, bg_green, bg_purple, bg_red, bg_yellow
• Foregrounds: fg_black, fg_blue, fg_cyan, fg_gray, fg_green, fg_purple, fg_red, fg_yellow
• Effects: bold, italics, standout, underline

Stylable Components:

• menu_cursor_style: Style of the cursor (default: ("fg_red", "bold")).
• menu_highlight_style: Style of the selected entry (default: ("standout",)).
• search_highlight_style: Style of matched search strings (default: ("fg_black", "bg_yellow", "bold")).
• shortcut_key_highlight_style: Style of shortcut keys (default: ("fg_blue",)).
• shortcut_brackets_highlight_style: Style of brackets around shortcuts (default: ("fg_gray",)).
• status_bar_style: Style of the status bar (default: ("fg_yellow", "bg_black")).
• multi_select_cursor_style: Style of the multi-selection cursor (default: ("fg_yellow", "bold")).
• multi_select_cursor_brackets_style: Style of brackets in multi-select (default: ("fg_gray",)).

Other Visual Options:

• title: A string, multiline string, or list of strings displayed above the menu.
• status_bar: A string, multiline string, list of strings, or a callable that takes the current entry and returns a string.
• menu_cursor: Define a custom cursor string (default: "> ") or set to None to disable.

The package can be used directly in shell scripts. The exit code is the 1-based index of the selected entry, or 0 if canceled.

Key CLI Arguments:

• -m, --multi-select: Enables multi-select mode (implies --stdout).
• -p, --preview-command: Command for previews. Use {} as a placeholder.
• --stdout: Prints selected indices to stdout (separated by ;) in addition to the exit status.
• -r, --preselected-entries: Comma-separated list of strings to pre-select.
• -R, --preselected-indices: Comma-separated list of numeric indices to pre-select.
• -t, --title: Set the menu title.
• -s, --case-sensitive: Enable case-sensitive search.
• --skip-empty-entries: Skip empty string entries.

# Example: Preview files using 'bat' from the command line
simple-term-menu -p "bat --color=always {}" \
                 --preview-size 0.75 \
                 $(find . -maxdepth 1 -type f)