LinuxCommandLibrary

whiptail

Display dialog boxes from shell scripts

TLDR

Display a simple message

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

Display a boolean choice, returning the result through the exit code
$ whiptail --title "[title]" --yesno "[message]" [height_in_chars] [width_in_chars]
copy

Customise the text on the yes/no buttons
$ whiptail --title "[title]" --yes-button "[text]" --no-button "[text]" --yesno "[message]" [height_in_chars] [width_in_chars]
copy

Display a text input box
$ [result_variable_name]="$(whiptail --title "[title]" --inputbox "[message]" [height_in_chars] [width_in_chars] [default_text] 3>&1 1>&2 2>&3)"
copy

Display a password input box
$ [result_variable_name]="$(whiptail --title "[title]" --passwordbox "[message]" [height_in_chars] [width_in_chars] 3>&1 1>&2 2>&3)"
copy

Display a multiple-choice menu
$ [result_variable_name]=$(whiptail --title "[title]" --menu "[message]" [height_in_chars] [width_in_chars] [menu_display_height] "[value_1]" "[display_text_1]" "[value_n]" "[display_text_n]" ..... 3>&1 1>&2 2>&3)
copy

SYNOPSIS

whiptail --title title [options]

PARAMETERS

--title title
    Specifies the title of the dialog box.

--backtitle backtitle
    Specifies the backtitle of the dialog box.

--clear
    Clears the screen when exiting.

--default-button button
    Sets the default button to be selected initially (yes/no).

--yes-button text
    Sets the text for the 'Yes' button.

--no-button text
    Sets the text for the 'No' button.

--cancel-button text
    Sets the text for the 'Cancel' button.

--ok-button text
    Sets the text for the 'OK' button.

--msgbox text height width
    Displays a message box with the given text, height, and width.

--yesno text height width
    Displays a yes/no box with the given text, height, and width.

--textbox file height width
    Displays the content of the given file in a text box with the given height and width.

--inputbox text height width [init]
    Displays an input box with the given text, height, width, and initial value. The user's input is printed to standard error.

--passwordbox text height width
    Displays a password box (input is masked) with the given text, height, and width. The user's input is printed to standard error.

--menu text height width menu_height tag item ...
    Displays a menu box with the given text, height, width, and menu options. The selected tag is printed to standard error.

--checklist text height width list_height tag item status ...
    Displays a checklist box with the given text, height, width, and list options. The selected tags are printed to standard error, one per line.

--radiolist text height width list_height tag item status ...
    Displays a radio list box with the given text, height, width, and list options. The selected tag is printed to standard error.

--gauge text height width percentage
    Displays a gauge with the given text, height, width, and initial percentage. Input is read from standard input to update the gauge, with 'XXX' indicating 100% and 'YYY' clearing the gauge.

--nocancel
    Removes the 'Cancel' button.

--defaultno
    Make "No" the default (in "Yes/No" boxes).

--ascii-lines
    Draw lines/borders using ASCII characters instead of UTF-8.

--separate-output
    For checklist/radiolist, output each item on a separate line.

--output-fd fd
    Use file descriptor fd for output.

--scrolltext
    Forces the widget to scroll through the text, rather than buffering it.

--topleft
    Put window in top-left corner.

--version
    Show program's version number and exit.

--help
    Display help message and exit.

DESCRIPTION

Whiptail is a command-line utility used to display dialog boxes from shell scripts. It is a reimplementation of dialog using ncurses, offering a more lightweight alternative. Whiptail enables you to create interactive scripts with various dialog types, such as message boxes, input boxes, checklist boxes, menu boxes, and more. This allows users to interact with your scripts in a user-friendly way without a graphical interface. The program is widely utilized in automated systems and configuration scripts to create menus that guide the user through the tasks. Whiptail offers enhanced control over dialog appearance compared to alternatives, and its simplicity integrates well with standard command-line workflows. It can return the user's input, choice or exit code that can be used in a script to proceed accordingly. The output is printed to standard error, unless redirected.

EXIT CODES

Whiptail returns different exit codes depending on user interaction:
0: OK (e.g., user pressed OK, selected an option).
1: Cancel (e.g., user pressed Cancel, ESC).
255: An error occurred.

REDIRECTION

Whiptail writes the user input or selected menu/checklist options to standard error (stderr). Redirection of standard error is often required to capture the output of whiptail into a variable in the script:
variable=$(whiptail --inputbox "Enter your name:" 10 40 "" 2>&1 > /dev/tty)

HISTORY

Whiptail emerged as a lightweight and portable alternative to the 'dialog' utility. It leverages the ncurses library to create text-based user interfaces in shell scripts. It gained popularity due to its efficiency, ease of use and has become a standard tool for creating interactive command-line applications and installation scripts.

SEE ALSO

dialog(1)

Copied to clipboard