Guide · Open source
How to use gum: interactive prompts for shell scripts
Updated · written with AI from the project's own documentation and checked against our catalogue data
Gum is a command-line tool from Charmbracelet that adds interactive pieces to shell scripts and aliases, such as menus, text prompts, confirmation questions, file pickers, spinners and styled output. It is aimed at developers who write bash scripts or dotfile aliases and want simple prompts without writing Go or another program. After this guide you will know how to install gum, call its main commands and combine them into a short script.
gumcharmbracelet/gum · ★ 24.6k · MIT Install options & downloads Quick start
- 1Install gum. Install it with your package manager, for example brew install gum on macOS or Linux, or use go install charm.land/gum/v2@latest if you have Go.
- 2Check the install. Run gum with a command such as gum --help or gum choose to confirm the program is on your path.
- 3Try a single prompt. Run gum input in a terminal and see the value it prints to standard output.
- 4Capture the output. Save the result to a variable with VAR=$(gum choose ...) so your script can use it.
- 5Add a confirmation. Use gum confirm with && so the next command runs only when the user answers yes.
- 6Wrap a slow command. Place gum spin --title before a command, after --, to show a spinner until it finishes.
- 7Adjust the look. Use --flags or GUM_ environment variables, and check gum <command> --help for the options.
What gum does and when to use it
Gum is built on the Bubbles and Lip Gloss libraries, but you use it without writing any Go code. Each feature is a single command you call from bash or a similar shell.
Gum suits short prompts inside scripts and aliases. It is not meant for large interactive programs, and it only works in the terminal, so it is not a choice for a graphical or web interface.
- Menus to pick an option (gum choose)
- Text prompts (gum input, gum write)
- Confirmation questions (gum confirm)
- File pickers (gum file)
- Spinners and styled output (gum spin, gum style)
Install gum on macOS, Linux or Windows
The simplest route is a package manager. The README lists Homebrew for macOS or Linux, pacman for Arch Linux, and dnf for Fedora or EPEL 10. On Windows it lists WinGet and Scoop. Other options in the README include Nix, Flox, apt for Debian/Ubuntu, and FreeBSD packages.
If you have Go installed, you can instead install it with go install. Gum is a separate program, so it must be present on the machine that runs your script.
# macOS or Linux
brew install gum
# Arch Linux
pacman -S gum
# Fedora or EPEL 10
dnf install gum
# Windows (via WinGet or Scoop)
winget install charmbracelet.gum
scoop install charm-gum
# With Go
go install charm.land/gum/v2@latestAsk the user a question with gum choose and gum input
gum choose shows a list and prints the option the user picks to standard output. Save that output to a variable or file to use it later. gum input prompts for a single line of text and accepts a placeholder.
Set a placeholder with --placeholder, or a starting value with --value.
- gum choose prints to stdout, so capture it with CARD=$(gum choose ...)
- Use --limit or --no-limit with choose or filter to allow multiple selections
gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert"
gum input --placeholder "scope"Confirm an action before it runs
gum confirm exits with code 0 for yes and 1 for no, so you can use it with && and || in a shell script. The example below only removes the file if the user confirms.
gum confirm && rm file.txt || echo "File not removed"Show a spinner around a long command
gum spin displays a spinner while a command runs and stops it when the command exits. Put the command after --. Add --show-output to view or pipe its output.
The README lists these spinner types: line, dot, minidot, jump, pulse, points, globe, moon, monkey, meter and hamburger.
gum spin --spinner dot --title "Buying Bubble Gum..." -- sleep 5Customize prompts with flags or environment variables
You can set options with --flags on the command line or with GUM_ environment variables. Flags override values set in the environment. Run gum <command> --help to see each command's options.
- Flags such as --prompt, --width, --placeholder and --foreground
- Environment variables such as GUM_INPUT_PROMPT and GUM_INPUT_WIDTH
export GUM_INPUT_PROMPT="* "
export GUM_INPUT_WIDTH=80
gum input --placeholder "What's up?"Build a small guided commit helper
The README's tutorial combines gum commands into a helper for writing Conventional Commits. It asks for the type, scope, summary and description, then asks for confirmation before committing.
Save each answer to a variable as you go, then pass them to git. The full example is in the repository under examples/commit.sh.
TYPE=$(gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert")
SCOPE=$(gum input --placeholder "scope")
SUMMARY=$(gum input --value "$TYPE$SCOPE: " --placeholder "Summary of this change")
DESCRIPTION=$(gum write --placeholder "Details of this change")
gum confirm "Commit changes?" && git commit -m "$SUMMARY" -m "$DESCRIPTION"What people use it for
- A guided helper that asks for a Conventional Commit type, scope and summary before running git commit.
- A confirmation step before a script deletes files.
- A file picker that opens the chosen file in your editor, using $EDITOR $(gum file $HOME).
- A spinner over a long-running command so the terminal does not look frozen.
- A styled box printed by gum style around a message in a script.
Frequently asked questions
Is gum free to use?
Gum is released under the MIT licence, according to the project's repository details. The MIT licence allows use, modification and redistribution, so you can use it in personal and team scripts.
What do I need to run gum?
The source lists no prerequisites. Gum is a separate program that must be installed on any machine that runs your script, and it only works in a terminal.
How do I install gum on Ubuntu or Debian?
The README gives an apt repository setup from repo.charm.sh, followed by sudo apt update && sudo apt install gum. Alternatively, download a binary or package from the releases page.
Can gum be used without writing Go?
Yes. Each gum feature is a single command you call from bash or a similar shell, so you do not need to write any Go or another program.
What are gum's alternatives?
The comparable projects listed for this item are fzf, dialog, whiptail and prompt libraries such as inquirer.js. Dialog and whiptail draw full-screen text boxes, while inquirer.js is a JavaScript library rather than a shell command.
Why does gum choose not print anything useful to my terminal?
gum choose prints the selected option to standard output. Save it with a variable such as CARD=$(gum choose ...) or redirect it to a file to use the result later.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Gum is a good fit for developers who write bash scripts or dotfile aliases and want simple, consistent prompts, spinners or styled output without building a UI. It is not the right choice if you need a graphical or web interface, a large interactive application, or if you cannot install a separate binary on the machine.
Install options & downloads