Table of Contents

Dialog - Terminal Menu Creator

Dialog is a script-driven menu and text interface generation tool. For example, it has file pickers, menus, checklists, confirmations, calendars, progress bars, etc.

The official documentation and downloads are at https://invisible-island.net/dialog/#documentation.

More screenshots and examples of all widgets are available at https://invisible-island.net/dialog/dialog-figures.html.

Install

In Debian and most Linux distributions it's as simple as using the package manager to install:

apt install dialog
dpkg -L dialog
dialog --version
dialog --help
man dialog

If you want to build from source, simply download, configure, and make:

wget ftp://ftp.invisible-island.net/dialog/dialog.tar.gz
tar xzf dialog.tar.gz
cd dialog-1.3-20210324 # Or whatever it is
./configure --help | less # Check options
./configure
make
./dialog --version
./dialog --help
make install  # optional

Example usage

Here is an example of a menu with a list of choices:

# Generate a menu
dialog --menu "Open mail" 20 40 10 \
 "Account 1" "~/.muttrc.1" "Account 2" "~/.muttrc.2" \
 2>answer.txt
# answer.txt will contain 'Account 1' or 'Account 2'

Here is another example that shows how to get output a different way. This is out it is done in the examples in the source code.

# Create temp stream for current shell
exec 3>&1    
 
# Prompt with dialog and get response
user_text=$(dialog --inputbox Testing 0 0 2>&1 1>&3)
 
# Store return value of dialog process. 0 = success.
# Check if it's 0 to confirm they didn't cancel
exit_code=$?
 
# Close the temp stream
exec 3>&-
 
# Print the results
Echo "Program exit code: $exit_code"
echo "User input: $user_text"

Available options

Below you will find a list of all the options and menus available. Also refer to https://invisible-island.net/dialog/dialog-figures.html for screenshots and examples of all widgets.

There are also numerous script examples in the source code in a directory called samples/

$ dialog --help

cdialog (ComeOn Dialog!) version 1.2-20130523
Copyright 2000-2012,2013 Thomas E. Dickey
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

* Display dialog boxes from shell scripts *

Usage: dialog <options> { --and-widget <options> }
where options are "common" options, followed by "box" options

Special options:
  [--create-rc "file"]
Common options:
  [--ascii-lines] [--aspect <ratio>] [--backtitle <backtitle>] [--beep]
  [--beep-after] [--begin <y> <x>] [--cancel-label <str>] [--clear]
  [--colors] [--column-separator <str>] [--cr-wrap] [--date-format <str>]
  [--default-button <str>] [--default-item <str>] [--defaultno]
  [--exit-label <str>] [--extra-button] [--extra-label <str>]
  [--help-button] [--help-label <str>] [--help-status] [--hfile <str>]
  [--hline <str>] [--ignore] [--input-fd <fd>] [--insecure] [--item-help]
  [--keep-tite] [--keep-window] [--last-key] [--max-input <n>]
  [--no-cancel] [--no-collapse] [--no-cr-wrap] [--no-items] [--no-kill]
  [--no-label <str>] [--no-lines] [--no-mouse] [--no-nl-expand]
  [--no-ok] [--no-shadow] [--no-tags] [--nook] [--ok-label <str>]
  [--output-fd <fd>] [--output-separator <str>] [--print-maxsize]
  [--print-size] [--print-version] [--quoted] [--scrollbar]
  [--separate-output] [--separate-widget <str>] [--shadow]
  [--single-quoted] [--size-err] [--sleep <secs>] [--stderr] [--stdout]
  [--tab-correct] [--tab-len <n>] [--time-format <str>] [--timeout <secs>]
  [--title <title>] [--trace <file>] [--trim] [--version] [--visit-items]
  [--yes-label <str>]
Box options:
  --buildlist    <text> <height> <width> <tag1> <item1> <status1>...
  --calendar     <text> <height> <width> <day> <month> <year>
  --checklist    <text> <height> <width> <list height> <tag1> <item1> <status1>...
  --dselect      <directory> <height> <width>
  --editbox      <file> <height> <width>
  --form         <text> <height> <width> <form height> <label1> <l_y1> <l_x1> <item1> <i_y1> <i_x1> <flen1> <ilen1>...
  --fselect      <filepath> <height> <width>
  --gauge        <text> <height> <width> [<percent>]
  --infobox      <text> <height> <width>
  --inputbox     <text> <height> <width> [<init>]
  --inputmenu    <text> <height> <width> <menu height> <tag1> <item1>...
  --menu         <text> <height> <width> <menu height> <tag1> <item1>...
  --mixedform    <text> <height> <width> <form height> <label1> <l_y1> <l_x1> <item1> <i_y1> <i_x1> <flen1> <ilen1> <itype>...
  --mixedgauge   <text> <height> <width> <percent> <tag1> <item1>...
  --msgbox       <text> <height> <width>
  --passwordbox  <text> <height> <width> [<init>]
  --passwordform <text> <height> <width> <form height> <label1> <l_y1> <l_x1> <item1> <i_y1> <i_x1> <flen1> <ilen1>...
  --pause        <text> <height> <width> <seconds>
  --prgbox       <text> <command> <height> <width>
  --programbox   <text> <height> <width>
  --progressbox  <text> <height> <width>
  --radiolist    <text> <height> <width> <list height> <tag1> <item1> <status1>...
  --rangebox     <text> <height> <width> <min-value> <max-value> <default-value>
  --tailbox      <file> <height> <width>
  --tailboxbg    <file> <height> <width>
  --textbox      <file> <height> <width>
  --timebox      <text> <height> <width> <hour> <minute> <second>
  --treeview     <text> <height> <width> <list-height> <tag1> <item1> <status1> <depth1>...
  --yesno        <text> <height> <width>

Auto-size with height and width = 0. Maximize with height and width = -1.
Global-auto-size if also menu_height/list_height = 0.

.dialogrc file

You can specify settings in a ~/.dialogrc file. There might also be one in your system under /etc/dialogrc.

To generate a default rc file, run the following command.

# Create a ~/.dialogrc file
dialog --create-rc ~/.dialogrc

Then you'll have an rc file with all the color and options populated for you to modify.

Change colors

If you want to see some example rc files, check in the source code in a directory called samples/. For example whiptail.rc. Screenshots are available at https://invisible-island.net/dialog/dialog-figures.html#list_colors. Refer to the file dlg_colors.h in the source code for a list of available colors. There aren't a ton, but it looks like there is:

Also make sure use_color = ON and not OFF.

To override the default rc filename, set a DIALOGRC environment variable to specify the file you want to use.

Here is a sample .dialogrc file that has DevDungeon-ish themed colors:

.dialogrc
#
# Run-time configuration file for dialog
#
# Types of values:
#
# Number     -  <number>
# String     -  "string"
# Boolean    -  <ON|OFF>
# Attribute  -  (foreground,background,highlight?,underline?,reverse?)
 
# Set aspect-ration.
aspect = 0
# Set separator (for multiple widgets output).
separate_widget = ""
# Set tab-length (for textbox tab-conversion).
tab_len = 0
# Make tab-traversal for checklist, etc., include the list.
visit_items = OFF
# Shadow dialog boxes? This also turns on color.
use_shadow = OFF
# Turn color support ON or OFF
use_colors = ON
screen_color = (CYAN,BLACK,ON)
shadow_color = (RED,RED,ON)
dialog_color = (CYAN,BLACK,OFF)
title_color = (CYAN,BLACK,ON)
border_color = (CYAN,BLACK,ON)
button_active_color = (BLACK,CYAN,ON)
button_inactive_color = dialog_color
button_key_active_color = button_active_color
button_key_inactive_color = (WHITE,BLACK,ON)
button_label_active_color = (WHITE,CYAN,ON)
button_label_inactive_color = (WHITE,BLACK,ON)
inputbox_color = dialog_color
inputbox_border_color = dialog_color
searchbox_color = dialog_color
searchbox_title_color = title_color
searchbox_border_color = border_color
position_indicator_color = title_color
menubox_color = dialog_color
menubox_border_color = border_color
item_color = dialog_color
item_selected_color = button_active_color
tag_color = title_color
tag_selected_color = button_label_active_color
tag_key_color = button_key_inactive_color
tag_key_selected_color = (CYAN,BLACK,ON)
check_color = dialog_color
check_selected_color = button_active_color
uarrow_color = (RED,BLACK,ON)
darrow_color = uarrow_color
itemhelp_color = (WHITE,BLACK,OFF)
form_active_text_color = button_active_color
form_text_color = (WHITE,CYAN,ON)
form_item_readonly_color = (CYAN,WHITE,ON)
gauge_color = title_color
border2_color = dialog_color
inputbox_border2_color = dialog_color
searchbox_border2_color = dialog_color
menubox_border2_color = dialog_color