A tool for glamorous shell scripts. Leverage the power of Bubbles and Lip Gloss in your scripts and aliases without writing any Go code!
The above example is running from a single shell script (source).
Gum provides highly configurable, ready-to-use utilities to help you write useful shell scripts and dotfiles aliases with just a few lines of code.
Let's build a simple script to help you write Conventional Commits for your dotfiles.
Start with a #!/bin/sh.
#!/bin/shAsk for the commit type with gum choose:
gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert"Tip: this command itself will print to
stdoutwhich is not all that useful. To make use of the command later on you can save the stdout to a$VARIABLEorfile.txt.
Prompt for an (optional) scope for the commit:
gum input --placeholder "scope"Prompt for a commit message:
gum input --placeholder "Summary of this change"Prompt for a detailed (multi-line) explanation of the changes:
gum write --placeholder "Details of this change"Prompt for a confirmation before committing:
gum confirmexits with status0if confirmed and status1if cancelled.
gum confirm "Commit changes?" && git commit -m "$SUMMARY" -m "$DESCRIPTION"Putting it all together...
#!/bin/sh
TYPE=$(gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert")
SCOPE=$(gum input --placeholder "scope")
# Since the scope is optional, wrap it in parentheses if it has a value.
[[ -n "$SCOPE" ]] && SCOPE="($SCOPE)"
# Pre-populate the input with the type(scope): so that the user may change it
SUMMARY=$(gum input --value "$TYPE$SCOPE: " --placeholder "Summary of this change")
DESCRIPTION=$(gum write --placeholder "Details of this change")
# Commit these changes
gum confirm "Commit changes?" && git commit -m "$SUMMARY" -m "$DESCRIPTION"
Use a package manager:
# macOS or Linux
brew tap charmbracelet/tap && brew install charmbracelet/tap/gum
# Arch Linux (btw)
yay -S gum-bin
# Nix
nix-env -iA nixpkgs.gum
# Debian/Ubuntu
echo 'deb [trusted=yes] https://repo.charm.sh/apt/ * *' | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install gum
# Fedora
echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=0' | sudo tee /etc/yum.repos.d/charm.repo
sudo yum install gumOr download it:
- Packages are available in Debian and RPM formats
- Binaries are available for Linux, macOS, and Windows
Or just install it with go:
go install github.com/charmbracelet/gum@latestgum is designed to be embedded in scripts and supports all sorts of use
cases. Components are configurable and customizable to fit your theme and
use case.
You can customize with --flags. See gum <command> --help for a full view of
each command's customization and configuration options.
For example, let's use an input and change the cursor color, prompt color,
prompt indicator, placeholder text, width, and pre-populate the value:
gum input --cursor.foreground "#FF0" --prompt.foreground "#0FF" --prompt "* " \
--placeholder "What's up?" --width 80 --value "Not much, hby?"
Prompt for input with a simple command.
gum input > answer.text
Prompt for some multi-line text.
gum write > story.text
Use fuzzy matching to filter a list of values:
echo Strawberry >> flavors.text
echo Banana >> flavors.text
echo Cherry >> flavors.text
cat flavors.text | gum filter > selection.text
Choose an option from a list of choices.
echo "Pick a card, any card..."
CARD=$(gum choose --height 15 {{A,K,Q,J},{10..2}}" "{β ,β₯,β£,β¦})
echo "Was your card the $CARD?"You can also select multiple items with the --limit flag, which determines
the maximum of items that can be chosen.
echo "Pick your top 5 songs."
cat songs.txt | gum choose --limit 5Or, allow any number of selections with the --no-limit flag.
echo "What do you need from the grocery store?"
cat foods.txt | gum choose --no-limit
Confirm whether to perform an action. Exits with code 0 (affirmative) or 1
(negative) depending on selection.
gum confirm && rm file.txt || echo "File not removed"
Display a spinner while running a script or command. The spinner will automatically stop after the given command exits.
gum spin --spinner dot --title "Buying Bubble Gum..." -- sleep 5
Pretty print any string with any layout with one command.
gum style \
--foreground 212 --border-foreground 212 --border double \
--align center --width 50 --margin "1 2" --padding "2 4" \
'Bubble Gum (1Β’)' 'So sweet and so fresh!'
Combine text vertically or horizontally. Use this command with gum style to
build layouts and pretty output.
Tip: Always wrap the output of gum style in quotes to preserve newlines
(\n) when using it as an argument in the join command.
I=$(gum style --padding "1 5" --border double --border-foreground 212 "I")
LOVE=$(gum style --padding "1 4" --border double --border-foreground 57 "LOVE")
BUBBLE=$(gum style --padding "1 8" --border double --border-foreground 255 "Bubble")
GUM=$(gum style --padding "1 5" --border double --border-foreground 240 "Gum")
I_LOVE=$(gum join "$I" "$LOVE")
BUBBLE_GUM=$(gum join "$BUBBLE" "$GUM")
gum join --align center --vertical "$I_LOVE" "$BUBBLE_GUM"
format processes and formats bodies of text. gum format can parse markdown,
template strings, and named emojis.
# Format some markdown
gum format -- "# Gum Formats" "- Markdown" "- Code" "- Template" "- Emoji"
echo "# Gum Formats\n- Markdown\n- Code\n- Template\n- Emoji" | gum format
# Syntax highlight some code
cat main.go | gum format -t code
# Render text any way you want with templates
echo '{{ Bold "Tasty" }} {{ Italic "Bubble" }} {{ Color "99" "0" " Gum " }}' \
| gum format -t template
# Display your favorite emojis!
echo 'I :heart: Bubble Gum :candy:' | gum format -t emojiFor more information on template helpers, see the Termenv docs. For a full list of named emojis see the GitHub API.
See the examples directory for more real world use cases.
How to use gum in your daily workflows:
Prompt for input to write git commit messages with a short summary and
longer details with gum input and gum write.
Bonus points: use gum filter with the Conventional Commits
Specification as a
prefix for your commit message.
git commit -m "$(gum input --width 50 --placeholder "Summary of changes")" \
-m "$(gum write --width 80 --placeholder "Details of changes")"By default, gum filter will display a list of all files (searched
recursively) through your current directory, with some sensible ignore settings
(.git, node_modules). You can use this command to easily to pick a file and
open it in your $EDITOR.
$EDITOR $(gum filter)Pick from a running tmux session and attach to it. Or, if you're already in a
tmux session, switch sessions.
SESSION=$(tmux list-sessions -F \#S | gum filter --placeholder "Pick session...")
tmux switch-client -t $SESSION || tmux attach -t $SESSION
Filter through your git history searching for commit messages, copying the commit hash of the commit you select.
git log --oneline | gum filter | cut -d' ' -f1 # | copy
List all packages installed by your package manager (we'll use brew) and
choose which packages to uninstall.
brew list | gum choose --no-limit | xargs brew uninstallWeβd love to hear your thoughts on this project. Feel free to drop us a note!
Part of Charm.
Charmηη±εΌζΊ β’ Charm loves open source