display title --backtitle <backtitle> display backtitle --scrolltext force vertical scrollbars --topleft put window in top-left corner -h, --help print this message -v, --version print version information </code> ++++ ===== See Also ===== * [[dialog:ko]] * [[ncurses:ko]] * [[https://manpages.debian.org/stable/whiptail/whiptail.1.en.html|Debian whiptail(1)]] * [[https://packages.debian.org/stable/whiptail|Debian whiptail]] * [[https://packages.fedoraproject.org/pkgs/newt/newt/|Fedora newt]] * [[https://formulae.brew.sh/formula/newt|Homebrew newt]] ===== History ===== * codex:: 2026-08-10 기존 command와 switch coverage를 보존해 표준 ''whiptail:ko'' page로 migration하고 설치, FD 처리, exit status, 호환성, troubleshooting을 보강함. {{indexmenu>.#1|js}}

{{tag>[cli terminal tui whiptail newt slang shell]}} ====== whiptail ====== ''whiptail''은 shell script에서 message, 질문, menu, checklist, progress gauge를 표시하는 TUI utility다. ncurses 기반 ''dialog''와 달리 ''newt''/S-Lang 계열을 사용하며 widget 범위가 더 작다. ===== Summary ===== * 설치 프로그램, rescue 환경, 간단한 관리 script에서 대화형 입력을 받을 때 사용한다. * 선택값은 기본적으로 standard error로 출력한다. * ''dialog'' 호환 interface를 일부 제공하지만 option, widget, 표시, output 동작이 완전히 같지는 않다. ===== Installation ===== ==== Debian / Ubuntu ====


sudo apt update
sudo apt install whiptail

==== RHEL / Fedora ==== Fedora의 ''newt'' package가 ''whiptail'' executable을 제공한다.


sudo dnf install newt

==== macOS ==== Homebrew는 upstream ''newt'' distribution을 formula로 제공한다.


brew install newt

설치 후 현재 formula가 ''whiptail'' executable을 포함하는지 verification command로 확인한다. ==== Windows ==== 2026-08-10 기준 upstream과 Microsoft ''winget''에서 공식 Windows용 ''whiptail'' package 설치 방법은 확인되지 않는다. Windows에서는 WSL의 Linux 배포판 package를 사용하는 방법을 우선 검토한다. ==== Verification ====


command -v whiptail
whiptail --version

이 저장소의 base environment에서 확인한 version은 ''whiptail (newt): 0.52.20''이다. ===== Usage =====


whiptail --title "Message" --msgbox "Hello, World" 10 40

* ''**whiptail** [OPTIONS] WIDGET WIDGET_ARGUMENTS'' ===== Widgets ===== * ''**--msgbox** TEXT HEIGHT WIDTH'': OK message box를 표시한다. * ''**--yesno** TEXT HEIGHT WIDTH'': Yes/No 질문을 표시한다. * ''**--infobox** TEXT HEIGHT WIDTH'': 대기하지 않고 정보를 표시한다. * ''**--inputbox** TEXT HEIGHT WIDTH [INIT]'': 문자열을 입력받는다. * ''**--passwordbox** TEXT HEIGHT WIDTH [INIT]'': 입력 문자를 숨겨 문자열을 받는다. * ''**--textbox** FILE HEIGHT WIDTH'': text file을 표시한다. * ''**--menu** TEXT HEIGHT WIDTH LIST_HEIGHT [TAG ITEM]...'': 항목 하나를 선택한다. * ''**--checklist** TEXT HEIGHT WIDTH LIST_HEIGHT [TAG ITEM STATUS]...'': 여러 항목을 선택한다. * ''**--radiolist** TEXT HEIGHT WIDTH LIST_HEIGHT [TAG ITEM STATUS]...'': 단일 선택 목록을 표시한다. * ''**--gauge** TEXT HEIGHT WIDTH PERCENT'': standard input으로 받은 진행률을 표시한다. ===== Options ===== * ''**--clear**'': 종료할 때 화면을 지운다. * ''**--defaultno**'': No button을 기본값으로 둔다. * ''**--default-item** STRING'': menu의 초기 항목을 지정한다. * ''**--fullbuttons**'', ''**--fb**'': compact button 대신 full button을 사용한다. * ''**--nocancel**'': Cancel button을 숨긴다. * ''**--yes-button** TEXT'': Yes button text를 바꾼다. * ''**--no-button** TEXT'': No button text를 바꾼다. * ''**--ok-button** TEXT'': OK button text를 바꾼다. * ''**--cancel-button** TEXT'': Cancel button text를 바꾼다. * ''**--noitem**'': item 설명을 표시하지 않는다. * ''**--notags**'': tag를 표시하지 않는다. * ''**--separate-output**'': checklist 결과를 인용 없이 한 줄에 하나씩 출력한다. * ''**--output-fd** FD'': 결과를 지정한 file descriptor로 보낸다. * ''**--title** TITLE'': dialog box 제목을 표시한다. * ''**--backtitle** BACKTITLE'': 화면 상단 배경 제목을 표시한다. * ''**--scrolltext**'': vertical scrollbar를 강제로 표시한다. * ''**--topleft**'': window를 왼쪽 위에 배치한다. * ''**--help**'', ''**-h**'': help를 출력한다. * ''**--version**'', ''**-v**'': version을 출력한다. ===== Exit Status ===== ^ Status ^ 의미 ^ | ''0'' | Yes 또는 OK로 확정했다. | | ''1'' | No 또는 Cancel을 선택했다. | | ''255'' | Esc를 눌렀거나 내부 error가 발생했다. | ''255''만으로 사용자 Esc와 내부 error를 구분할 수 없으므로 필요하면 호출 전 terminal 조건과 error message를 함께 기록한다. ===== Examples ===== ==== Yes / No ====


if whiptail --defaultno --yesno "파일을 삭제하시겠습니까?" 10 40; then
    printf '%s\n' "사용자가 삭제를 승인했습니다."
else
    printf '%s\n' "취소했습니다."
fi

파괴적 동작에서는 ''--defaultno''를 사용하고, 실제 삭제 전에 대상과 복구 방법을 별도로 검증한다. ==== Menu 결과 받기 ==== ''whiptail''은 결과를 기본적으로 standard error에 쓴다. 기존 shell script에서 흔히 사용하는 FD swap을 적용한다.


action=$(whiptail --menu "시스템 설정 도구" 15 40 4 \
    "1" "네트워크 설정" \
    "2" "사용자 추가" \
    "3" "서비스 재시작" 3>&1 1>&2 2>&3)
status=$?

if [ "$status" -eq 0 ]; then
    case "$action" in
        "1") /path/to/network-setup.sh ;;
        "2") /path/to/user-add.sh ;;
        "3") systemctl restart some-service ;;
    esac
else
    printf '%s\n' "취소됨"
fi

기존의 간단한 menu pattern도 같은 방식으로 사용할 수 있다.


choice=$(whiptail --menu "옵션을 선택하세요" 15 30 4 \
    "1" "설치" \
    "2" "제거" \
    "3" "업데이트" 3>&1 1>&2 2>&3)

printf '선택: %s\n' "$choice"

==== Checklist ====


options=$(whiptail --checklist "패키지 선택" 15 40 4 \
    "nginx" "웹 서버" OFF \
    "mysql" "데이터베이스" ON \
    "php" "PHP 언어" OFF 3>&1 1>&2 2>&3)

printf '선택된 항목: %s\n' "$options"

tag에 공백이나 quote가 들어갈 수 있으면 기본 결과 문자열을 ''eval''로 해석하지 않는다. 가능하면 단순하고 통제된 tag를 사용하거나 ''--separate-output''과 ''--output-fd''를 조합해 line 단위로 읽는다. ==== Gauge ====


{
    for i in {1..100}; do
        printf '%s\n' "$i"
        sleep 0.1
    done
} | whiptail --gauge "처리 중..." 6 50 0

===== Keyboard ===== * Tab: button이나 field 사이를 이동한다. * Space: checklist 항목을 선택하거나 해제한다. * Enter: 현재 선택을 확정한다. * Esc: widget을 취소하고 일반적으로 status ''255''로 종료한다. * Up, Down, PgUp, PgDn: list나 text를 이동한다. ===== Troubleshooting ===== ==== 변수에 결과가 들어오지 않음 ==== * widget 결과는 기본적으로 standard error로 출력된다. * ''3>&1 1>&2 2>&3'' FD swap 또는 ''--output-fd''를 사용한다. * command substitution 직후 ''$?''를 저장해 취소 여부를 확인한다. ==== Dash로 시작하는 text가 option으로 처리됨 ==== option parsing을 끝내기 위해 독립된 ''--'' token을 widget argument 앞의 적절한 위치에 둔다. 구체적인 placement는 설치본의 manual을 확인하고 test한다. ==== TUI가 보이지 않거나 깨짐 ==== * 대화형 terminal인지 ''[ -t 0 ] && [ -t 1 ]''로 확인한다. * ''TERM'' 값과 ''infocmp "$TERM"'' 결과를 확인한다. * CI나 cron에는 plain-text 또는 environment-variable 기반 fallback을 제공한다. ===== Compatibility ===== * ''whiptail''은 ''newt''를 사용하고 ''dialog''는 일반적으로 ncurses를 사용한다. * ''whiptail''에는 ''dialog''의 ''calendar'', ''timebox'', ''tailbox'', ''form'' 등 여러 widget이 없다. * 공통 option처럼 보여도 mapping이나 동작이 다를 수 있다. 예를 들어 ''dialog''는 일부 whiptail option을 자체 이름으로 mapping하거나 무시한다. * 두 implementation 사이의 자동 fallback은 사용 widget과 output을 양쪽에서 test한 뒤 적용한다. ===== Help ===== ++++ whiptail --help |


Box options:
	--msgbox   
	--yesno    
	--infobox   
	--inputbox    [init]
	--passwordbox    [init]
	--textbox   
	--menu     [tag item] ...
	--checklist     [tag item status]...
	--radiolist     [tag item status]...
	--gauge    
Options: (depend on box-option)
	--clear                         clear screen on exit
	--defaultno                     default no button
	--default-item          set default string
	--fb, --fullbuttons             use full buttons
	--nocancel                      no cancel button
	--yes-button              set text of yes button
	--no-button               set text of no button
	--ok-button               set text of ok button
	--cancel-button           set text of cancel button
	--noitem                        don't display items
	--notags                        don't display tags
	--separate-output               output one line at a time
	--output-fd                 output to fd, not stdout
	--title                  display title
	--backtitle <backtitle>         display backtitle
	--scrolltext                    force vertical scrollbars
	--topleft                       put window in top-left corner
	-h, --help                      print this message
	-v, --version                   print version information
</code>
++++

===== See Also =====
  * [[dialog:ko]]
  * [[ncurses:ko]]
  * [[https://manpages.debian.org/stable/whiptail/whiptail.1.en.html|Debian whiptail(1)]]
  * [[https://packages.debian.org/stable/whiptail|Debian whiptail]]
  * [[https://packages.fedoraproject.org/pkgs/newt/newt/|Fedora newt]]
  * [[https://formulae.brew.sh/formula/newt|Homebrew newt]]

===== History =====
  * codex:: 2026-08-10 기존 command와 switch coverage를 보존해 표준 ''whiptail:ko'' page로 migration하고 설치, FD 처리, exit status, 호환성, troubleshooting을 보강함.

{{indexmenu>.#1|js}}