whiptail

Display a simple message

$ whiptail --title "[title]" --msgbox "[message]" [height_in_chars] [width_in_chars]

$ whiptail --title "[title]" --yesno "[message]" [height_in_chars] [width_in_chars]

$ whiptail --title "[title]" --yes-button "[text]" --no-button "[text]" --yesno "[message]" [height_in_chars] [width_in_chars]

$ [result_variable_name]="$(whiptail --title "[title]" --inputbox "[message]" [height_in_chars] [width_in_chars] [default_text] 3>&1 1>&2 2>&3)"

$ [result_variable_name]="$(whiptail --title "[title]" --passwordbox "[message]" [height_in_chars] [width_in_chars] 3>&1 1>&2 2>&3)"

$ [result_variable_name]=$(whiptail --title "[title]" --menu "[message]" [height_in_chars] [width_in_chars] [menu_display_height] ["value_1" "display_text_1" "value_2" "display_text_2" ...] 3>&1 1>&2 2>&3)

whiptail [options] --box-type text height width [box-options]

--yesno text height width
    Displays a simple Yes/No question dialog. Returns 0 for Yes, 1 for No.

--msgbox text height width
    Displays a message box with an OK button.

--infobox text height width
    Displays a message box but returns immediately. Useful for showing progress.

--inputbox text height width [init]
    Prompts for text input. The entered text is printed to stderr. init is optional default text.

--passwordbox text height width [init]
    Similar to --inputbox, but masks input characters.

--textbox file height width
    Displays the content of a text file, allowing scrolling.

--menu text height width list-height [tag item ...]
    Presents a scrollable menu of items. The selected tag is printed to stderr.

--radiolist text height width list-height [tag item status ...]
    Displays a radio button list, allowing single selection. status can be ON or OFF.

--checklist text height width list-height [tag item status ...]
    Displays a checklist, allowing multiple selections. status can be ON or OFF.

--gauge text height width [percent]
    Displays a gauge or progress bar. Reads percentage from stdin to update.

--title text
    Specifies the title to be displayed at the top of the dialog box.

--backtitle text
    Specifies a title to be displayed in the background.

--ok-button text
    Sets the text for the OK button (default is 'Ok').

--cancel-button text
    Sets the text for the Cancel button (default is 'Cancel').

--default-item tag
    Sets the default selected item in menu, radiolist, or checklist boxes.

--defaultno
    Makes 'No' the default button for --yesno boxes.

--nocancel
    Omits the 'Cancel' button from dialog boxes.

--noitem
    Suppresses the display of item tags in menu and list boxes.

--noescape
    Disables interpretation of escape sequences like \n, \t, etc., in text.

--scrolltext
    Allows text in message boxes and text boxes to be scrolled if it exceeds the box size.

--topleft
    Positions the dialog box at the top-left corner of the screen.

--hscroll int
    Sets the initial horizontal scroll position for --textbox.

--fb
    Attempts to use the Linux frame buffer device. May require root privileges.

--logfd fd
    Redirects debug output to the specified file descriptor.

Whiptail is a lightweight utility that allows shell scripts to display various types of user-friendly dialog boxes in a text-based terminal environment. It is a clone of the more feature-rich dialog program, but built upon the newt library instead of ncurses, making it suitable for environments where ncurses is not preferred or available. It enables script developers to create interactive elements like message boxes, input fields, menus, yes/no prompts, and progress bars, significantly enhancing user interaction for command-line applications without requiring a graphical desktop environment. Whiptail communicates results (like chosen menu items or input text) via standard error, and indicates user actions (OK/Cancel) via its exit status.

Whiptail primarily communicates results via its exit status (0 for OK/Yes, 1 for Cancel/No/Escape) and by printing selected data (like input text or menu tags) to stderr. Therefore, shell scripts must redirect stderr to capture this output (e.g., OUTPUT=$(whiptail ... 3>&1 1>&2 2>&3)). It provides a text-based interface, limiting its aesthetic flexibility compared to graphical toolkits.

After a whiptail command finishes, its exit status indicates the user's action:
0: User pressed OK, Yes, or selected an item.
1: User pressed Cancel, No, or pressed the ESC key.
255: An error occurred or the dialog was interrupted (e.g., by Ctrl+C).

For dialog types that return user input (e.g., --inputbox, --menu), whiptail prints the result to stderr. To capture this output into a shell variable, you typically need to swap standard output and standard error using file descriptor redirection. A common pattern is:
VARIABLE=$(whiptail --inputbox "Enter your name:" 10 50 2>&1 1>&3-)
where 3 is a temporary file descriptor.

Whiptail emerged as a clone of the well-known dialog utility. While dialog typically relies on the ncurses library, whiptail was developed to use the lighter-weight newt (Not GNU Emacs Widget Toolkit) library. This design choice often makes whiptail more suitable for minimal systems or embedded environments, and it gained prominence through its use in installers and configuration scripts for systems like Debian and Ubuntu.

dialog(1), ncurses(3), newt(3)