BSDDIALOG(1)

🌸 NAME 🌸

bsddialog — TUI dialogs

This is the bsddialog(1) page from the General Commands Manual, bestie. Short, iconic, to the point 💅

✨ SYNOPSIS ✨

bsddialog --help | --version
bsddialog [--option] --dialog text rows cols [dialog-argument]
          [--option]
bsddialog ...  --dialog1 ... [--and-dialog --dialog2 ...] ...

💅 DESCRIPTION 💅

Okay so bsddialog builds Text User Interface dialogs and widgets — main character energy for your terminal, fr fr.

The option --help prints a brief list of features and exits. The option --version prints the version and exits. The option --and-dialog builds another dialog unless the previous one returns Error, ESC or Cancel.

Each dialog accepts text to print a message inside, rows and cols to set height and width, 0 for autosize and -1 for fullscreen.

The possible input from the user interface is printed to standard error at exit.

🎀 Options 🎀

The following options can change the default behavior of the utility and are common to some dialog. Customization era, let's go ✨

• --alternate-screen — set alternate screen mode if the terminal and curses(3) provide it. If enabled, bsddialog draws to the alternate screen and restores the main screen after exit. See “smcup” in terminfo(5). terminal magic, iconic ✨
• --ascii-lines — ASCII characters to draw lines. simple but cute 🎀
• --backtitle backtitle — screen title.
• --begin-x x — set dialog horizontal position, -1 center, 0 left screen.
• --begin-y y — set dialog vertical position, -1 center, 0 top screen.
• --bikeshed — random settings. Colors, title delimiter, button delimiter; see theme features. Title margin. Buttons always active or TAB to switch focus with other components, see --switch-buttons. Zero padding with time output; see --time-format. Zero padding with date output; see --date-format. User Interface date format for --datebox; see --datebox-format.
• --cancel-exit-code retval — set an exit code value for the “Cancel” button.
• --cancel-label label — label for the “Cancel” button.
• --clear-dialog — hide the dialog at exit.
• --clear-screen — clear the screen, wait a dialog if built.
• --columns-per-row columns — try to set the number of columns for a row of text with autosizing; default 10.
• --cr-wrap — keep new line in text also if it contains a \n, see --text-unchanged.
• --datebox-format format — string to customize --datebox interface, possible values: “d/m/y”, “m/y/d”, “y/m/d”.
• --date-format format — string accepted by strftime(3) to customize the output of --datebox and --calendar.
• --default-button label — focus on the button with label on startup.
• --default-item name — focus on the item with name, for Checklist, Menu, Radiolist and Treeview.
• --default-no — focus on “Cancel” or “No” button on startup.
• --disable-esc — disable ESC key to quit.
• --error-exit-code retval — set an exit code value for the bsddialog errors.
• --esc-exit-code retval — set an exit code value for the ESC key.
• --extra-button — add a button with “Extra” label.
• --extra-exit-code retval — set an exit code value for the “Extra” button.
• --extra-label label — set label for the “Extra” button.
• --left1-button label — add a button with label.
• --left1-exit-code retval — set an exit code for --left1-button.
• --left2-button label — add a button with label.
• --left2-exit-code retval — set an exit code for --left2-button.
• --left3-button label — add a button with label.
• --left3-exit-code retval — set an exit code for --left3-button.
• --help-button — add a button with “Help” label.
• --help-exit-code retval — set an exit code value for the “Help” button.
• --help-label label — set label for “Help” button.
• --help-print-items — print also the selected items or form values if the “Help” button is pressed.
• --help-print-name — print the name of the focused item if the “Help” button is pressed also with --item-bottom-desc.
• --hfile filename — open filename in a Textbox if F1 key is pressed.
• --hline string — dialog subtitle.
• --hmsg string — open a Msgbox with string if the F1 key is pressed.
• --ignore — do not exit with unknown options.
• --insecure — print * to hide passwords while typing, white space otherwise.
• --item-bottom-desc — set a help string for each item of a Checklist, Form, Menu, Mixedform, Passwordform, Radiolist and Treeview to display at the bottom screen side.
• --item-depth — specify a margin for items, available for Checklist, Menu and Radiolist.
• --item-prefix — set a string to prefix each item of a Checklist, Menu, Radiolist or Treeview.
• --load-theme file — load theme from file.
• --max-input size — maximum length of the input for --inputbox and --passwordbox, default 2048.
• --no-cancel — do not show “Cancel” button.
• --no-descriptions — do not display item descriptions for Checklist, Menu, Radiolist or Treeview; mutually exclusive with --no-names.
• --no-lines — do not draw borders and lines.
• --no-names — do not display item names for Checklist, Menu and Radiolist; mutually exclusive with --no-descriptions.
• --no-ok — do not draw “OK” button.
• --no-shadow — do not draw the shadow of the dialog.
• --ok-label label — set label for “OK” button.
• --ok-exit-code retval — set an exit code value for the “Ok” button.
• --normal-screen — set normal screen mode. bsddialog does not restore the previous screen after exit. See “rmcup” in terminfo(5).
• --output-fd fd — print input from user interface to the specified file descriptor.
• --output-separator sep — set a separator for the items in output, default white space.
• --print-maxsize — screen size. This option can be used without a dialog.
• --print-size — print dialog height and width at exit.
• --print-version — print version. This option can be used without a dialog.
• --quoted — quote items in output, default only when necessary.
• --right1-button label — add a button with label.
• --right1-exit-code retval — set an exit code for --right1-button.
• --right2-button label — add a button with label.
• --right2-exit-code retval — set an exit code for --right2-button.
• --right3-button label — add a button with label.
• --right3-exit-code retval — set an exit code for --right3-button.
• --save-theme file — save the current theme. This option can be used without a dialog.
• --separate-output — print selected items separated by a new line and avoid quoting.
• --shadow — show a shadow for the dialog, enabled by default.
• --single-quoted — use single quote for items in output.
• --sleep secs — wait secs seconds to close the dialog.
• --stderr — print input from user interface to standard error, default.
• --stdout — print input from user interface to standard output.
• --switch-buttons — enable focus switching between buttons and input components pressing TAB, otherwise buttons are always active and ENTER key closes the dialog. Suitable for: --form, --inputbox, --mixedform, --passwordbox, --passwordform, --timebox, --calendar and --datebox.
• --tab-escape — replace \t with a tab in text.
• --tab-len spaces — number of spaces to print a TAB in text.
• --text-escape — enable escapes in text, and here's the whole palette bestie:
  • \Z0 — black.
  • \Z1 — red.
  • \Z2 — green.
  • \Z3 — yellow.
  • \Z4 — blue.
  • \Z5 — magenta.
  • \Z6 — cyan.
  • \Z7 — white.
  • \Zb — bold.
  • \ZB — disable bold.
  • \Zd — half bright.
  • \ZD — disable half bright.
  • \Zk — blink.
  • \ZK — disable blinking.
  • \Zr — reverse foreground and background.
  • \ZR — disable reverse.
  • \Zs — highlight.
  • \ZS — disable highlighting.
  • \Zu — underline.
  • \ZU — disable underline.
  • \Zn — disable each customization.
• --text-unchanged — disable text modification. By default text is changed before it's printed in the dialog. If it contains at least a \n, each new line and TAB is converted to a space, and subsequent spaces are merged. Otherwise new line characters are preserved and a TAB becomes a space.
• --theme theme — set theme, possible values: “3d”, “blackwhite”, “flat”.
• --time-format format — string accepted by strftime(3) to customize the output of --timebox.
• --timeout-exit-code retval — set an exit code value for the --pause timeout.
• --title title — dialog title.

🔑 Keys 🔑

The following keys are available at runtime:

• Ctrl+l — redraw the dialog.
• F1 — see --hfile and --hmsg.
• SPACE — select menu item.
• UP, DOWN, LEFT, RIGHT, -, +, HOME, END, PAGEUP, PAGEDOWN, Ctrl+p, Ctrl+n, TAB — navigate elements and set value, depending on the dialog.

🪄 Dialogs 🪄

The following dialogs are available:

• --calendar text rows cols [day month year] — dialog to select a date.
• --checklist text rows cols menurows [name desc status] ... — checklist to select some item from a list via the SPACE key. An item has a name, desc and a default status specified by “on” or “off”. The names of the selected items are printed to standard error. menurows is the graphical height of the list, 0 for autosize.
• --datebox text rows cols [day month year] — dialog to select a date.
• --form text rows cols formrows [label ylabel xlabel init yfield xfield fieldlen maxletters] ... — bestie, this is your forms era 🌸. It gets a list of strings via forms. Each form has a label at position ylabel and xlabel, plus a field for input at yfield and xfield. fieldlen is the field width: if it’s negative it’s readonly and the width is the absolute value; if it’s 0 the field becomes readonly and its value is the init width. The field input is not printed to output if it’s readonly. maxletters is the maximum input length, and if it’s 0 its value is fieldlen. init is the default value in the field. formrows is the graphical height of the list, 0 for autosize. Slay.
• --gauge text rows cols [percentage] — a dialog with a bar that shows percentage, then it waits to read XXX from standard input, then the first string replaces percentage and the following strings replace text until the next XXX; the loop ends reading EOF. Gauge girlie is lowkey iconic 💅.
• --infobox text rows cols — a dialog without buttons to display a message and exit immediately. Poof, gone ✨.
• --inputbox text rows cols [init] — a dialog to get a string in input; init is the default value.
• --menu text rows cols menurows [name desc] ... — builds a menu to select an item from a list. SPACE is equivalent to ENTER. An item has a name and a desc. The name of the selected item is printed to standard error. menurows is the graphical height of the list, 0 for autosize.
• --mixedform text rows cols formrows [label ylabel xlabel init yfield xfield fieldlen maxletters flag] ... — dialog to get a list of strings via forms. A form has a label at position ylabel and xlabel, and a field to get the input at position yfield and xfield. fieldlen is the field width: if it’s negative it’s readonly and the width is the absolute value; if it’s 0 the field becomes readonly and its value is the init width. The field input is not printed to output if fieldlen is less than or equal to 0. maxletters is the maximum input length, and if it’s 0 its value is fieldlen. init is the default value in the field. flag can customize the field: 0 normal, 1 hide typed characters, 2 readonly. formrows is the graphical height of the list, 0 for autosize.
• --mixedgauge text rows cols mainperc [minilabel miniperc] ... — dialog to show a main bar representing mainperc from 0 to 100. It also has some mini bar with a minilabel string and a miniperc with a value from 0 and 100 or negative to print a descriptive string: -1 “Succeeded”, -2 “Failed”, -3 “Passed”, -4 “Completed”, -5 “Checked”, -6 “Done”, -7 “Skipped”, -8 “In Progress”, -9 to hide miniperc, -10 “N/A”, -11 “Pending”, otherwise “UNKNOWN”. No cap, the negative numbers are doing a whole language 😭.
• --msgbox text rows cols — dialog to display a message without the “Cancel” button.
• --passwordbox text rows cols [init] — dialog to get a password; init is the default value. Secretive bestie vibes 🙈.
• --passwordform text rows cols formrows [label ylabel xlabel init yfield xfield fieldlen maxletters] ... — dialog to get a list of passwords, equivalent to --form except typed characters are hidden.
• --pause text rows cols seconds — dialog runs until seconds timeout expires or a button is pressed. Tick tock ⏳.
• --radiolist text rows cols menurows [name desc status] ... — radiolist to select at most an item from a list via the SPACE key. An item has a name, desc and a default status specified by "on" or "off". The name of the selected item is printed to standard error. menurows is the graphical height of the list, 0 for autosize.
• --rangebox text rows cols min max [init] — dialog to select a value between min and max; init is the default value.
• --textbox file rows cols — opens and prints file. TAB changes button. Extra keys 0, h, l, k, j are available to navigate the text. The “OK” button is renamed “EXIT”. Very “I’m just gonna scroll” energy 💀.
• --timebox text rows cols [hour min sec] — dialog to select a time.
• --treeview text rows cols menurows [depth name desc status] ... — equivalent to Radiolist with --item-depth and --no-name.
• --yesno text rows cols — “Yes-No Question”, and the “OK” and “Cancel” buttons are renamed “Yes” and “No”.

---

🌿 ENVIRONMENT

The following environment variables take effect only on startup; other options can override their setting.

• NO_COLOR — if present and not an empty string (regardless of its value), it’s equivalent to --theme blackwhite.
• BSDDIALOG_ERROR, BSDDIALOG_OK, BSDDIALOG_CANCEL, BSDDIALOG_HELP, BSDDIALOG_EXTRA, BSDDIALOG_TIMEOUT, BSDDIALOG_ESC, BSDDIALOG_LEFT1, BSDDIALOG_LEFT2, BSDDIALOG_LEFT3, BSDDIALOG_RIGHT1, BSDDIALOG_RIGHT2, BSDDIALOG_RIGHT3 — set exit codes.
• BSDDIALOG_THEMEFILE file — equivalent to --load-theme file.

📁 FILES

The theme file $HOME/.bsddialog.conf is read on startup if it exists. Bestie, that’s your lil’ config moment 🎀.

🚦 EXIT STATUS

The bsddialog utility exits 255 on unsuccessful, otherwise depending on the button or key pressed the following values can be returned:

• 0 — “OK”, “Yes” or “Exit” button.
• 1 — “Cancel” or “No” button.
• 2 — “Help” button.
• 3 — “Extra” button.
• 4 — Timeout.
• 5 — ESC key.
• 6 — Left1 generic button.
• 7 — Left2 generic button.
• 8 — Left3 generic button.
• 9 — Right1 generic button.
• 10 — Right2 generic button.
• 11 — Right3 generic button.

🌟 EXAMPLES

Backtitle, title and message:

bsddialog --backtitle MESSAGE --title Msgbox --msgbox Message 0 0

Yes-No Question and theme:

bsddialog --theme blackwhite --yesno Question 10 30

Save a custom theme:

bsddialog --save-theme mytheme.txt --infobox "Saving theme..." 0 0

Load a custom theme:

bsddialog --load-theme mytheme.txt --infobox "Custom theme" 0 0

Checklist:

bsddialog --checklist Checklist 0 0 3 N1 D1 off N2 D2 on N3 D3 off

Form:

bsddialog --form Form 0 0 0 L1: 0 0 X 0 4 20 25 L2: 1 0 Y 1 4 20 25

Multi-dialog:

bsddialog --normal-screen --begin-y 1 --yesno Continue? 0 0 \
--and-dialog --begin-y 10 --infobox Yes 0 0

Bikeshed:

bsddialog --bikeshed --inputbox Example 0 0
bsddialog --bikeshed --datebox Example 0 0

Mixedgauge:

bsddialog --sleep 3 --mixedgauge Example 10 30 60 L1 " -1" L2 30

Mixedgauge script:

perc=0
while [ $perc -le 100 ]
do
        bsddialog --sleep 1 --title Mixedgauge          \
                --mixedgauge "\nExample...\n" 0 0 $perc \
                "Hidden"   " -9"                        \
                "Label 1"  " -4"                        \
                "Label 2"  " -4"                        \
                "Label 3"  $perc

        perc=`expr $perc + 20`
done

Gauge script:

i=1
for c in A B C D E F G H
do
        sleep 1
        echo XXX
        echo "$(expr $(expr $i "*" 100) "/" 8)"
        echo "[$i/8] Char: $c"
        echo XXX
        if [ $i -eq 8 ]
        then
                sleep 1
                echo EOF
        fi
        i=`expr $i + 1`
done | bsddialog --title Gauge --gauge "Starting..." 10 70

🔁 COMPATIBILITY

Outdated options are retained for compatibility; properly equivalent options are used:

• --and-widget → --and-dialog
• --calendar <text> 2 <cols> → --calendar <text> 0 <cols>
• --clear → --clear-screen
• --colors → --text-escape
• --defaultno → --default-no
• --exit-label → --ok-label
• --help-status → --help-print-items
• --help-tags → --help-print-name
• --item-help → --item-bottom-desc
• --keep-tite → --alternate-screen
• --no-items → --no-descriptions
• --no-label → --cancel-label
• --no-tags → --no-names
• --nocancel → --no-cancel
• --nook → --no-ok
• --separator → --output-separator
• --yes-label → --ok-label

👀 SEE ALSO

Check out bsddialog(3), strftime(3), and terminfo(5).

📜 HISTORY

The bsddialog utility first appeared in FreeBSD 14.0.

💖 AUTHORS

bsddialog was written by Alfonso Sabato Siciliano ⟨asiciliano@FreeBSD.org⟩.

bsddialog provides also a subset of the functionality described in the dialog manual. The following features were reimplemented:

Options: --and-widget, --ascii-lines, --backtitle, --cancel-label, --clear, --colors, --cr-wrap, --date-format, --defaultno, --default-button, --default-no, --default-item, --exit-label, --extra-button, --extra-label, --help, --help-button, --help-label, --help-status, --help-tags, --hfile, --hline, --ignore, --insecure, --item-help, --keep-tite, --max-input, --no-cancel, --nocancel, --no-items, --no-label, --no-lines, --no-ok, --nook, --no-shadow, --no-tags, --ok-label, --output-fd, --output-separator, --print-maxsize, --print-size, --print-version, --quoted, --separate-output, --separator, --shadow, --single-quoted, --sleep, --stderr, --stdout, --tab-len, --time-format, --title, --version, --yes-label.

Keys: Ctrl-l, F1.

Dialogs: --calendar, --checklist, --form, --gauge, --infobox, --inputbox, --menu, --mixedform, --mixedgauge, --msgbox, --passwordbox, --passwordform, --pause, --radiolist, --rangebox, --textbox, --timebox, --treeview, --yesno.

Some feature differs in input, output, or behavior. Compatibility is not a priority for future development.

🫶 THANKS TO

Baptiste Daroussin ⟨bapt@FreeBSD.org⟩, Ed Maste ⟨emaste@FreeBSD.org⟩, Juraj Lutter ⟨otis@FreeBSD.org⟩ and Trenton Schulz for suggestions, help, and testing.

---

Source/version cutie: Debian, stamped June 22, 2025, page tag BSDDIALOG(1) — bye bestie, go make your terminal absolutely slay 💅✨