gum 사용법 2026: 쉘 스크립트를 대화형 CLI로 바꾸는 실전 가이드

gum 사용법을 찾는 사람은 보통 두 부류입니다. Bash로 자동화는 이미 하고 있지만 read, select, printf만으로는 사용자 경험이 너무 딱딱한 사람, 또는 사내 배포 스크립트·개인 dotfiles·Git 커밋 도우미에 선택창과 확인창을 빠르게 붙이고 싶은 사람입니다. 이 글의 최종 결과물은 gum 하나로 입력, 선택, 필터, 확인, 스타일 출력까지 갖춘 작은 대화형 쉘 스크립트입니다. 명령은 복사해서 실행할 수 있게 구성했고, 실제로 내려받아 검증한 v0.17.0 기준으로 작성했습니다.

검증일: 2026-07-25. GitHub API, README, release asset, shallow clone, Linux x86_64 바이너리 실행 결과를 함께 확인했습니다.

최종 결과물: gum 사용법으로 만드는 대화형 배포 전 체크 CLI

완성하면 다음 흐름을 가진 release-check.sh를 만들 수 있습니다.

• 작업 종류를 gum choose로 선택합니다.
• 릴리스 메모를 gum input 또는 gum write로 받습니다.
• 변경 파일 목록을 gum filter로 좁힙니다.
• 실행 직전에 gum confirm으로 한 번 더 확인합니다.
• 결과 로그와 안내 문구를 gum style, gum log, gum format으로 보기 좋게 출력합니다.

이 글에서는 실제 터미널이 필요한 명령과 CI·헤드리스 환경에서 안전하게 쓸 수 있는 명령을 분리합니다. 제가 실행한 환경에는 /dev/tty가 없어 choose, filter, table은 오류가 재현됐고, 이 점은 본문에서 그대로 다룹니다.

원클릭 설치: 가장 짧은 gum 설치 경로

macOS와 Homebrew가 있는 Linux에서는 README의 첫 번째 경로가 가장 짧습니다.

brew install gum
gum --version

Ubuntu/Debian 서버에서 패키지 저장소를 등록하려면 다음 순서입니다.

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update
sudo apt install gum
gum --version

Go 개발 환경이 이미 있으면 소스 빌드 설치도 가능합니다. 단, 이번 검증 환경에는 go가 설치되어 있지 않아 이 명령은 실행하지 않았습니다.

go install github.com/charmbracelet/gum@latest

패키지 매니저를 쓰기 어렵다면 GitHub Release에서 운영체제·아키텍처에 맞는 tarball을 내려받아 임시 경로에서 먼저 검증합니다. 제 검증 환경은 Linux x86_64였습니다.

mkdir -p /tmp/gum-check && cd /tmp/gum-check
curl -L -o gum_0.17.0_Linux_x86_64.tar.gz   https://github.com/charmbracelet/gum/releases/download/v0.17.0/gum_0.17.0_Linux_x86_64.tar.gz
curl -L -o checksums.txt   https://github.com/charmbracelet/gum/releases/download/v0.17.0/checksums.txt
sha256sum gum_0.17.0_Linux_x86_64.tar.gz
grep 'gum_0.17.0_Linux_x86_64.tar.gz$' checksums.txt
tar -xzf gum_0.17.0_Linux_x86_64.tar.gz
./gum_0.17.0_Linux_x86_64/gum --version

실행 결과에서 해시가 일치했고 버전은 다음처럼 확인됐습니다.

69ee169bd6387331928864e94d47ed01ef649fbfe875baed1bbf27b5377a6fdb  gum_0.17.0_Linux_x86_64.tar.gz
69ee169bd6387331928864e94d47ed01ef649fbfe875baed1bbf27b5377a6fdb  gum_0.17.0_Linux_x86_64.tar.gz
gum version v0.17.0 (6045525)

1단계: gum이 제공하는 명령을 먼저 확인하기

gum --help는 어떤 하위 명령을 조합할 수 있는지 빠르게 보여줍니다.

gum --help

검증한 v0.17.0 help에는 다음 명령이 노출됐습니다.

README와 gum.go를 대조해 보니 version-check도 CLI 구조에 포함되어 있습니다. 자동화에서 특정 버전 이상을 요구할 때 확인용으로 둘 수 있습니다.

2단계: 복사해서 시작하는 release-check.sh

아래 예제는 실제 터미널에서 실행하는 것을 전제로 합니다. choose, input, filter, confirm은 사용자의 키 입력이 필요한 Bubble Tea 기반 UI라서 /dev/tty가 있는 터미널에서 실행해야 합니다.

cat > release-check.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail

command -v gum >/dev/null || {
  echo "gum이 필요합니다. 먼저 brew install gum 또는 apt install gum을 실행하세요." >&2
  exit 1
}

TYPE=$(gum choose "patch" "minor" "major" --header "릴리스 종류를 고르세요")
TITLE=$(gum input --placeholder "릴리스 제목" --prompt "title> ")
NOTES=$(gum write --placeholder "주요 변경 사항을 적고 Ctrl+D로 종료")

CHANGED=$(git status --short | gum filter --no-limit --height 12 --placeholder "검토할 파일 선택")

printf "%s
" "$CHANGED" | gum style --border rounded --padding "1 2" --foreground 212

gum confirm "${TYPE} 릴리스 체크를 계속할까요?" || exit 1

gum spin --spinner dot --title "테스트 실행 중" -- bash -c 'sleep 1; echo ok >/tmp/gum-release-check.txt'

gum log --level info "release type=${TYPE}"
gum format "# $gum 사용법 2026: 쉘 스크립트를 대화형 CLI로 바꾸는 실전 가이드

${NOTES}"
SH
chmod +x release-check.sh
./release-check.sh

이 스크립트는 실제 배포를 하지 않습니다. gum spin 안에서도 /tmp/gum-release-check.txt만 만드는 안전한 예제로 두었습니다. 실제 프로젝트에 붙일 때는 sleep 1 부분을 npm test, pytest, go test ./... 같은 검증 명령으로 바꾸면 됩니다.

3단계: 헤드리스 환경에서 먼저 걸러야 하는 명령

자동화 서버, 크론, 일부 CI처럼 TTY가 없는 환경에서는 모든 gum 명령이 같은 방식으로 동작하지 않습니다. 이번 검증에서 다음 명령은 성공했습니다.

gum style --border rounded --padding '0 1' --foreground 212 'Daily Info Lab'
gum format '# Gum

**Markdown** 테스트'
gum log --level info 'draft generated'

관찰한 출력입니다.

╭────────────────╮
│ Daily Info Lab │
╰────────────────╯
INFO draft generated

반대로 선택 UI가 필요한 명령은 /dev/tty가 없으면 실패했습니다.

printf 'feat
fix
docs
' | gum filter --placeholder 'type' --height 5 --value fe

실제 오류는 다음과 같았습니다.

unable to run filter: could not open a new TTY: open /dev/tty: no such device or address

gum choose --limit 1 feat fix docs도 같은 계열의 오류를 냈고, gum table 역시 이 환경에서는 failed to start tea program: could not open a new TTY로 실패했습니다. 그래서 CI에서 gum을 쓰려면 “사람이 보는 로컬 스크립트”와 “비대화형 배치 스크립트”를 분리하는 편이 안전합니다.

4단계: dotfiles용 Conventional Commit 도우미 만들기

Gum README의 튜토리얼은 Conventional Commit 메시지를 만드는 예제로 시작합니다. 한국어 dotfiles나 개인 프로젝트에 맞춰 조금 더 실행 가능한 형태로 줄이면 다음과 같습니다.

cat > gum-commit.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail

TYPE=$(gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert" --header "commit type")
SCOPE=$(gum input --placeholder "scope, 예: shell 또는 blog" --prompt "scope> ")
SUMMARY=$(gum input --value "${TYPE}(${SCOPE}): " --placeholder "변경 요약")
DESCRIPTION=$(gum write --placeholder "상세 설명. 비워도 됩니다. Ctrl+D로 종료")

gum style --border rounded --padding "1 2" "${SUMMARY}"
gum confirm "이 메시지로 커밋할까요?" || exit 1

git commit -m "$SUMMARY" -m "$DESCRIPTION"
SH
chmod +x gum-commit.sh

주의할 점은 gum confirm 다음에 destructive 명령을 바로 붙일 수 있다는 점입니다. 예를 들어 README의 gum confirm "Are you sure?" && rm file.txt 형태는 짧지만, 팀 스크립트에서는 삭제 대상 경로를 먼저 출력하고 한 번 더 확인하는 방식이 낫습니다.

5단계: 스타일을 환경변수로 고정하기

README는 --flags와 환경변수 두 가지 커스터마이징 방식을 안내합니다. 반복 사용하는 스타일은 스크립트 상단에 환경변수로 모아 두면 명령마다 긴 색상 옵션을 반복하지 않아도 됩니다.

export GUM_INPUT_CURSOR_FOREGROUND="#FF0"
export GUM_INPUT_PROMPT_FOREGROUND="#0FF"
export GUM_INPUT_PLACEHOLDER="입력하세요"
export GUM_INPUT_PROMPT="› "
export GUM_INPUT_WIDTH=80

PROJECT_NAME=$(gum input --placeholder "project-name")
gum style --border rounded --padding "0 2" --foreground 212 "${PROJECT_NAME}"

스크립트를 다른 사람에게 배포한다면 테마 값은 파일 상단에 모으고, 실제 동작 명령과 분리하세요. 그래야 색상만 바꾸는 PR이 로직 변경과 섞이지 않습니다.

6단계: gum을 쓰면 좋은 경우와 아닌 경우

핵심은 “로직은 Bash/Make/Python에 두고, 사람과 만나는 지점만 gum으로 감싼다”입니다. 이렇게 하면 gum이 없어도 대체 경로를 만들기 쉽고, UI 코드를 과하게 늘리지 않아도 됩니다.

7단계: 검증 체크리스트

설치 후에는 다음 순서로 확인하세요.

command -v gum
gum --version
gum --help | sed -n '1,40p'
gum style --border rounded --padding '0 1' 'hello'
gum log --level info 'gum is ready'

실제 터미널에서는 아래 대화형 명령도 확인합니다.

gum choose "dev" "staging" "prod"
printf 'api
worker
web
' | gum filter --height 8
gum confirm "계속할까요?"

성공 기준은 간단합니다. 버전이 표시되고, style 명령이 박스 형태의 문자열을 출력하며, 대화형 명령에서 키보드로 항목을 선택할 수 있으면 기본 설치는 끝난 것입니다.

문제 해결

could not open a new TTY가 나온다

크론, 비대화형 SSH, 일부 컨테이너, 웹 기반 실행기에서는 /dev/tty가 없을 수 있습니다. 이번 검증에서도 같은 오류를 재현했습니다. 해결책은 세 가지입니다.

# 1) 로컬 터미널에서 직접 실행
./release-check.sh

# 2) CI에서는 gum 선택 UI를 건너뛰고 환경변수로 값을 주입
RELEASE_TYPE=patch ./ci-release-check.sh

# 3) Docker/SSH 실행 시 TTY 할당
ssh -t user@host './release-check.sh'
docker run -it --rm your-image ./release-check.sh

gum: command not found가 나온다

패키지 매니저 설치 후 PATH가 갱신되지 않았을 가능성이 큽니다.

which gum
echo "$PATH"
# Homebrew 예시
brew --prefix gum

Apple Silicon Mac에서 Homebrew를 /opt/homebrew에 설치했다면 셸 초기화 파일에 Homebrew shellenv가 들어갔는지 확인하세요.

go install이 실패한다

현재 go.mod는 Go 1.25.8을 선언합니다. 오래된 Go로 go install github.com/charmbracelet/gum@latest를 실행하면 의존성 해석이나 빌드가 실패할 수 있습니다. 이 경우에는 Go를 올리거나 공식 release tarball, Homebrew, apt 저장소 설치 경로를 쓰는 편이 빠릅니다.

색상이 기대와 다르게 보인다

Gum은 터미널 색상 프로필과 출력 대상에 영향을 받습니다. 파이프나 로그 파일로 보낼 때는 터미널에서 보는 것과 다르게 보일 수 있습니다. 중요한 배포 로그라면 색상에만 의미를 담지 말고 gum log --level warn처럼 텍스트 레벨도 같이 남기세요.

요약: gum 사용법을 적용할 때의 기준

gum은 쉘 스크립트를 완전히 다른 언어로 갈아엎지 않고도 선택창, 입력창, 확인창, 진행 표시를 붙일 수 있는 CLI 도구입니다. Charmbracelet이 만든 Bubble Tea·Lip Gloss 기반 UI를 Go 코드 없이 가져오는 것이 장점이고, MIT 라이선스라 개인 dotfiles부터 팀 내부 스크립트까지 적용하기 쉽습니다.

다만 gum은 “사람이 보는 터미널 UI”에 강합니다. 서버에서 조용히 돌아가는 배치 작업의 핵심 로직을 gum에 의존시키면 TTY 문제를 만날 수 있습니다. 로컬 개발자 경험을 개선하는 얇은 UI 레이어로 쓰고, 실제 빌드·테스트·배포 명령은 기존 도구로 분리하는 구성이 가장 안전합니다.

관련해서 AI 코딩 도구 워크플로를 정리 중이라면 Orca 병렬 AI 코딩 에이전트 가이드와 Davia 문서화 가이드도 함께 보면 로컬 CLI 자동화 흐름을 잡는 데 도움이 됩니다.

FAQ

gum은 fzf를 대체하나요?

부분적으로만 겹칩니다. gum filter는 fuzzy 선택 UI를 제공하지만, gum 전체는 선택·입력·확인·스타일·스피너를 묶은 쉘 스크립트 UI 도구입니다. 순수 검색 성능이나 고급 필터링만 필요하면 fzf가 더 직접적입니다.

gum을 프로덕션 배포 스크립트에 넣어도 되나요?

로컬에서 사람이 직접 실행하는 배포 전 확인 스크립트에는 잘 맞습니다. 자동 배포 파이프라인에서는 TTY가 없는 경우가 많으므로 gum 없이도 실행되는 환경변수·플래그 기반 경로를 같이 두는 것이 안전합니다.

Windows에서도 사용할 수 있나요?

공식 README는 Winget과 Scoop 설치를 안내하고, GitHub Release에는 Windows zip asset도 있습니다. 다만 이 글의 실제 실행 검증은 Linux x86_64 바이너리로 했습니다.

v0.17.0에서 눈에 띄는 변경점은 무엇인가요?

최신 release notes 기준으로 choose, confirm, file, filter, input, pager, spin, style, table, write 등 여러 명령에 --padding 옵션이 추가됐습니다. 스크립트 UI를 맞출 때 여백을 더 일관되게 줄 수 있습니다.

공식 출처

• GitHub 저장소
• README 설치·명령 문서
• 최신 릴리스 v0.17.0
• Go 문서
• Charm 패키지 저장소
• 공식 이미지