Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
WHIPTAIL(1)		    General Commands Manual		   WHIPTAIL(1)

       whiptail	- display dialog boxes from shell scripts

       whiptail	 [  --title  title  ]  [ --backtitle backtitle ] [ --clear ] [
       --default-item string ] [ --defaultno ] [  --fb	]  [  --nocancel  ]  [
       --yes-button  text ] [ --no-button text ] [ --ok-button text ] [	--can-
       cel-button text ] [ --noitem [ ]	--output-fd fd ] [ --separate-output ]
       [ --scrolltext ]	[ --topleft ] box-options

       whiptail	 is a program that will	let you	present	a variety of questions
       or display messages using dialog	boxes from a shell script.  Currently,
       these types of dialog boxes are implemented:

       yes/no  box,  menu  box,	 input	box,  message box, text	box, info box,
       checklist box, radiolist	box gauge box, and password box.

	      The screen will be cleared to  the  screen  attribute  on	 exit.
	      This  doesn't  work  in  an xterm	(and descendants) if alternate
	      screen switching is enabled, because in that case	 slang	writes
	      to (and clears) an alternate screen.

	      The dialog box will open with the	cursor over the	No button.

       --default-item string
	      Set  the default item in a menu box.  Normally the first item in
	      the box is the default.

       --fb, --fullbuttons
	      Use full buttons.	(By default, whiptail uses compact buttons).

	      The dialog box won't have	a Cancel button.

       --yes-button text
	      Set the text of the Yes button.

       --no-button text
	      Set the text of the No button.

       --ok-button text
	      Set the text of the Ok button.

       --cancel-button text
	      Set the text of the Cancel button.

	      The menu,	checklist and  radiolist  widgets  will	 display  tags
	      only,  not  the  item  strings. The menu widget still needs some
	      items specified, but checklist and radiolist expect only tag and

	      Don't display tags in the	menu, checklist	and radiolist widgets.

	      For checklist widgets, output result one line at a time, with no
	      quoting.	This facilitates parsing by another program.

       --output-fd fd
	      Direct output to	the  given  file  descriptor.	Most  whiptail
	      scripts write to standard	error, but  error  messages  may  also
	      be written there,	depending on your script.

       --title title
	      Specifies	a title	string to be displayed at the top of the  dia-
	      log box.

       --backtitle backtitle
	      Specifies	a backtitle string to be displayed on the backdrop, at
	      the top of the screen.

	      Force the	display	of a vertical scrollbar.

	      Put window in top-left corner.

       -h, --help
	      Print a help message and exit.

       -v, --version
	      Print version information	and exit.

       Box Options

       --yesno text height width
	      A	yes/no dialog box of size height rows by width columns will be
	      displayed.  The string specified by text is displayed inside the
	      dialog box. If this string is too	long to	be fit in one line, it
	      will be automatically divided into multiple lines	at appropriate
	      places. The text string may also contain the sub-string "\n"  or
	      newline  characters  `\n'	 to  control line breaking explicitly.
	      This dialog box is useful	for asking questions that require  the
	      user  to answer either yes or no.	 The dialog box	has a Yes but-
	      ton and a	No button, in which the	user  can  switch  between  by
	      pressing the TAB key.

       --msgbox	text height width
	      A	message	box is very similar to a yes/no	box.  The only differ-
	      ence between a message box and a yes/no box is  that  a  message
	      box  has only a single OK	button.	You can	use this dialog	box to
	      display any message you like.  After reading  the	 message,  the
	      user  can	press the ENTER	key so that whiptail will exit and the
	      calling shell script can continue	its operation.

       --infobox text height width
	      An info box is basically a message box.  However,	in this	 case,
	      whiptail	will  exit immediately after displaying	the message to
	      the user.	The screen is not cleared when whiptail	exits, so that
	      the  message  will  remain on the	screen until the calling shell
	      script clears it later. This is useful when you want  to	inform
	      the  user	 that some operations are carrying on that may require
	      some time	to finish.

       --inputbox text height width [init]
	      An input box is useful when you want to ask questions  that  re-
	      quire  the user to input a string	as the answer. If init is sup-
	      plied it is used to initialize the input string.	When  inputing
	      the  string, the BACKSPACE key can be used to correct typing er-
	      rors. If the input string	is longer than the width of the	dialog
	      box, the input field will	be scrolled. On	exit, the input	string
	      will be printed on stderr.

       --passwordbox text height width [init]
	      A	password box is	similar	to an input box, except	the  text  the
	      user  enters is not displayed. This is useful when prompting for
	      passwords	or other sensitive information.	Be aware that if  any-
	      thing  is	 passed	 in "init", it will be visible in the system's
	      process table to casual snoopers.	Also, it is very confusing  to
	      the  user	 to  provide  them with	a default password they	cannot
	      see. For these reasons, using "init" is highly discouraged.

       --textbox file height width
	      A	text box lets you display the contents of a text file in a di-
	      alog  box.  It  is  like a simple	text file viewer. The user can
	      move through the	file  by  using	 the  UP/DOWN,	PGUP/PGDN  and
	      HOME/END keys available on most keyboards.  If the lines are too
	      long to be displayed in the box, the LEFT/RIGHT keys can be used
	      to  scroll  the  text region horizontally. For more convenience,
	      forward and backward searching functions are also	provided.

       --menu text height width	menu-height [ tag item ] ...
	      As its name suggests, a menu box is a dialog  box	 that  can  be
	      used  to present a list of choices in the	form of	a menu for the
	      user to choose. Each menu	entry consists of a tag	string and  an
	      item  string.  The  tag gives the	entry a	name to	distinguish it
	      from the other entries in	the menu. The item is a	short descrip-
	      tion  of the option that the entry represents. The user can move
	      between the menu entries by pressing the UP/DOWN keys, the first
	      letter  of  the  tag as a	hot-key. There are menu-height entries
	      displayed	in the menu at one time, but the menu will be scrolled
	      if  there	 are  more entries than	that. When whiptail exits, the
	      tag of the chosen	menu entry will	be printed on stderr.

       --checklist text	height width list-height [ tag item status ] ...
	      A	checklist box is similar to a menu box in that there are  mul-
	      tiple  entries  presented	in the form of a menu.	You can	select
	      and deselect items using the  SPACE  key.	  The  initial	on/off
	      state  of	each entry is specified	by status.  On exit, a list of
	      the tag strings of those entries that  are  turned  on  will  be
	      printed on stderr.

       --radiolist text	height width list-height  [ tag	item status ] ...
	      A	 radiolist  box	is similar to a	menu box.  The only difference
	      is that you can indicate which entry is currently	 selected,  by
	      setting its status to on.

       --gauge text height width percent
	      A	 gauge	box displays a meter along the bottom of the box.  The
	      meter indicates a	percentage.  New  percentages  are  read  from
	      standard	input,	one integer per	line.  The meter is updated to
	      reflect each new percentage.  If stdin is	XXX, the first follow-
	      ing  line	is a percentage	and subsequent lines up	to another XXX
	      are used for a new prompt.  The gauge exits when EOF is  reached
	      on stdin.

       whiptail	 interprets  arguments starting	with a dash "-"	as being argu-
       ments.  To avoid	this, and start	some text in, for example,  a  menubox
       item,  with a dash, whiptail honours the	getopt convention of accepting
       the special argument "--" which means that all following	arguments with
       dashes are to be	treated	verbatim and not parsed	as options.

       Exit  status  is	0 if whiptail is exited	by pressing the	Yes or OK but-
       ton, and	1 if the No or Cancel button is	pressed. Otherwise, if	errors
       occur  inside  whiptail	or whiptail is exited by pressing the ESC key,
       the exit	status is -1.

       Based on	the man	page for dialog(1) by:

       Savio Lam ( - version 0.3

       Stuart Herbert ( - patch for version 0.4

       Modifications for whiptail by:

       Enrique Zanardi (

       Alastair	McKinstry (

Whiptail Version 0.52.5		31 January 2007			   WHIPTAIL(1)


Want to link to this manual page? Use this URL:

home | help