Ruby wrapper for Charm's Gum. A tool for glamorous scripts.
This gem bundles the gum binary and provides an idiomatic Ruby API for all gum commands.
Add to your Gemfile:
bundle add gumOr install directly:
gem install gumrequire "gum"Prompt for single-line input:
name = Gum.input(placeholder: "Enter your name")Password input (masked):
password = Gum.input(password: true)With default value and custom prompt:
email = Gum.input(value: "user@", prompt: "> ", placeholder: "email")With character limit:
code = Gum.input(placeholder: "Enter code", char_limit: 6)Prompt for multi-line text input (Ctrl+D to submit):
description = Gum.write(placeholder: "Enter description...")With dimensions:
notes = Gum.write(width: 80, height: 10, header: "Notes")With line numbers:
content = Gum.write(show_line_numbers: true)Single selection (array):
color = Gum.choose(["red", "green", "blue"])Single selection (splat):
color = Gum.choose("red", "green", "blue")Multiple selection with limit:
colors = Gum.choose(["red", "green", "blue"], limit: 2)Unlimited selection:
colors = Gum.choose(["red", "green", "blue"], no_limit: true)With header and custom height:
choice = Gum.choose(options, header: "Pick one:", height: 10)Pre-selected items:
choice = Gum.choose(["a", "b", "c"], selected: ["b"])Single selection (array):
file = Gum.filter(Dir.glob("**/*.rb"))Single selection (splat):
file = Gum.filter("file1.rb", "file2.rb", "file3.rb")Multiple selection:
files = Gum.filter(Dir.glob("*"), limit: 5)Unlimited selection:
files = Gum.filter(items, no_limit: true)With placeholder and height:
selection = Gum.filter(items, placeholder: "Search...", height: 20)Disable fuzzy matching for exact search:
result = Gum.filter(items, fuzzy: false)Ask for yes/no confirmation:
if Gum.confirm("Delete file?")
File.delete(path)
endWith default value:
proceed = Gum.confirm("Continue?", default: true)Custom button labels:
Gum.confirm("Save changes?", affirmative: "Save", negative: "Discard")Start from current directory:
path = Gum.fileStart from specific directory:
path = Gum.file("~/Documents")Show hidden files:
path = Gum.file(all: true)Only show directories:
dir = Gum.file(directory_only: true)Scroll through content:
Gum.pager(File.read("README.md"))With line numbers:
Gum.pager(content, show_line_numbers: true)Soft wrap long lines:
Gum.pager(content, soft_wrap: true)With shell command:
Gum.spin("Installing...", command: "npm install")With Ruby block:
result = Gum.spin("Processing...") do
expensive_computation
endCustom spinner type:
Gum.spin("Loading...", spinner: :dot, command: "sleep 5")Available spinner types: :line, :dot, :minidot, :jump, :pulse, :points, :globe, :moon, :monkey, :meter, :hamburger
Basic styling:
styled = Gum.style("Hello", foreground: "212", bold: true)With border:
box = Gum.style("Content", border: :double, padding: "1 2")Multiple lines with alignment:
styled = Gum.style("Line 1", "Line 2", align: :center, width: 50)Full styling example:
styled = Gum.style(
"Bubble Gum",
foreground: "212",
border: :double,
border_foreground: "212",
align: :center,
width: 50,
margin: "1 2",
padding: "2 4"
)Available border types: :none, :hidden, :rounded, :double, :thick, :normal
Join text blocks horizontally or vertically:
box1 = Gum.style("A", border: :rounded, padding: "1 3")
box2 = Gum.style("B", border: :rounded, padding: "1 3")Horizontal join (default):
combined = Gum.join(box1, box2)Vertical join:
stacked = Gum.join(box1, box2, vertical: true)With alignment:
aligned = Gum.join(box1, box2, vertical: true, align: :center)Markdown:
Gum.format("# Hello\n- Item 1\n- Item 2", type: :markdown)Template (see Termenv docs for helpers):
Gum.format('{{ Bold "Hello" }} {{ Color "99" "0" " World " }}', type: :template)Emoji:
Gum.format("I :heart: Ruby :gem:", type: :emoji)
# => "I ❤️ Ruby 💎"Shorthand methods:
Gum::Format.markdown("# Hello")
Gum::Format.emoji("I :heart: Ruby")From array of arrays:
data = [["Alice", "30"], ["Bob", "25"]]
selection = Gum.table(data, columns: %w[Name Age])Just print (no selection):
Gum.table(data, columns: %w[Name Age], print: true)From CSV string:
Gum.table(File.read("data.csv"))With custom border:
Gum.table(data, columns: %w[Name Age], border: :rounded)Basic logging:
Gum.log("Application started", level: :info)Structured logging with key-value pairs:
Gum.log("User created", level: :info, user_id: 123, email: "[email protected]")With timestamp:
Gum.log("Error occurred", level: :error, time: :rfc822)Shorthand methods:
Gum::Log.debug("Debug message")
Gum::Log.info("Info message")
Gum::Log.warn("Warning message")
Gum::Log.error("Error message", code: 500)Available log levels: :debug, :info, :warn, :error, :fatal
Most commands support styling options as hashes. Common style properties include:
{
foreground: "212", # ANSI color code, hex (#ff0000), or name
background: "0",
bold: true,
italic: true,
underline: true,
strikethrough: true,
faint: true,
}Example with input styling:
Gum.input(
placeholder: "Enter name",
cursor: { foreground: "#FF0" },
prompt_style: { foreground: "#0FF" }
)GUM_INSTALL_DIR- Override the path to the gum binary
For commands not covered by the Ruby API, you can execute gum directly:
Gum.execute("choose", "a", "b", "c", "--limit", "2")After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
rake gem:ruby # Build pure Ruby gem (no binary)
rake gem:arm64-darwin # Build macOS ARM64 gem
rake gem:x86_64-darwin # Build macOS Intel gem
rake gem:arm64-linux # Build Linux ARM64 gem
rake gem:x86_64-linux # Build Linux x86_64 gem
rake package # Build all platform gems
rake download # Download all binariesBug reports and pull requests are welcome on GitHub at https://github.com/marcoroth/gum-ruby.
The gem is available as open source under the terms of the MIT License.
- Charm for creating the amazing gum tool
- Inspired by
litestream-rubyfor the native binary packaging approach
Charm Ruby is not affiliated with or endorsed by Charmbracelet, Inc.
Part of Charm Ruby.
Lipgloss • Bubble Tea • Bubbles • Glamour • Huh? • Harmonica • Bubblezone • Gum • ntcharts
The terminal doesn't have to be boring.
