|
Modular, Hierarchical Bash Library for Stunning Terminal UIs. Funny Gums is a professional-grade Bash toolkit designed to build complex, responsive, and visually rich terminal applications. It bridges the gap between simple shell scripts and full-blown TUIs by providing a layered architecture powered by gum.
|
|
# Ubuntu/Debian - Add Charm repository for latest gum
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 jq
# For other systems: https://github.com/charmbracelet/gum#installation#!/usr/bin/env bash
source ./funny_gums.sh
ui_box "Welcome" "Funny Gums is ready!"
cpu_temp=$(get_cpu_temp_live)
echo "Mainframe Temperature: ${cpu_temp}°C"| Resource | Description |
|---|---|
| 📖 User Guide | Comprehensive reference for all modules. |
| 🚀 Getting Started | Step-by-step installation and basic patterns. |
| 🏛️ Architecture | Deep dive into the tiered design and dependency chain. |
| 💡 Examples | Walkthroughs of the examples/ directory. |
lib/
├── core/ 🧱 - Foundation: Colors, Text, Logging, Sudo
├── ui/ 📦 - Visualization: Boxes, Gauges, Tables, Inputs
├── mod/ ⚙️ - Domain: CPU, GPU, Storage, Network
└── app/ 🏗️ - Logic: Dashboards and Command Runners
Apache License 2.0. See LICENSE for details.
A modular Bash library providing terminal UI components powered by gum from Charm.
- 🎨 Colors - ANSI color variables and helper functions
- 📍 Cursor - Terminal cursor control (movement, visibility, clearing)
- 🔄 Spinner - Multiple animation presets + native gum spin integration
- 📝 Logging - Structured logging with
gum logintegration - 🖼️ UI - High-level wrappers for boxes, confirms, inputs, selections, tables, and pagers
- 📊 Dashboard - Multi-step progress dashboard with in-place updates
- 🏃 Runner - Command execution with spinner/dashboard integration
- 🔐 Sudo - Credential management with keepalive
- 🎯 Terminal-Aware Emojis - 3-tier system with automatic VS16 fallbacks for GNOME Terminal
- 🖥️ System Monitoring - CPU, memory, storage, GPU, and network metrics
- Bash 4.0+
- gum - Required for UI components
- jq - Required for efficient JSON parsing
- Standard Utils - awk, sed, grep, date, tput (usually pre-installed)
Development (for contributors):
- shellcheck - Bash linting
- shfmt - Code formatting
Optional (for system monitoring modules):
- inxi - System information
- lm-sensors - Hardware monitoring (provides
sensorscommand) - smartmontools - Storage health (provides
smartctlcommand) - hdparm - Disk performance metrics
- dmidecode - Hardware details
- acpi - Power management info
Install gum from Charm's official repository (recommended):
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 jqOptional system monitoring tools:
sudo apt install inxi lm-sensors smartmontools hdparm dmidecodeDevelopment dependencies (for contributing):
sudo apt install shellcheck shfmtFor macOS, Arch, Fedora, and other systems, see the official gum installation guide.
# macOS (Homebrew)
brew install gum jq
# Arch Linux
pacman -S gum jq
# From source
go install github.com/charmbracelet/gum@latest# Clone to your preferred location
git clone https://github.com/ksokolowski/funny_gums.git
cd funny_gums# Use the built-in dependency checker
make deps# Run a simple example to verify everything works
bash examples/markdown_preview.sh README.mdYou have two options:
Option A: Source everything (easiest, loads all modules)
#!/usr/bin/env bash
source /path/to/funny_gums/funny_gums.sh
ui_box "Hello" "Funny Gums is ready!"Option B: Source specific modules (faster, minimal footprint)
#!/usr/bin/env bash
source /path/to/funny_gums/lib/core/term/colors.sh
source /path/to/funny_gums/lib/ui/layout/ui.sh
echo "${GREEN}Success!${RESET}"
ui_confirm "Continue?" && echo "Let's go!"Common patterns and use cases:
# Colors
echo "${RED}Error:${RESET} Something went wrong"
colorize "$GREEN" "Success!"
# UI components
ui_box "Welcome" "This is a styled box"
if ui_confirm "Continue?"; then
echo "Proceeding..."
fi
choice=$(ui_choose "Option A" "Option B" "Option C")
# Spinner with native gum types
ui_spin_type dot "Loading..." sleep 2
ui_spin_type moon "Processing..." my_command
# Tables and pagers
cat data.csv | ui_table
cat README.md | ui_format | ui_pager
# Logging (including structured)
log_init "/tmp/myapp.log"
log_info "Application started"
log_structured info "Processing" file "data.csv" rows 100
log_fatal "Application stopped"
|
|
VS16 emojis (like
| Terminal Tier | Examples | Emoji Handling |
|---|---|---|
| full | Kitty, WezTerm, Ghostty, iTerm | Full VS16 support |
| compatible | GNOME Terminal, Tilix | Colorful fallbacks (🟡 instead of |
| legacy | xterm, TTY | Text fallbacks ([!] instead of |
Usage: Simply use the $EMOJI_* variables - they auto-adapt to the terminal:
source lib/core/text/emojis.sh
echo "$EMOJI_WARNING Config missing" # ⚠️ or 🟡 or [!]
echo "$EMOJI_CPU Processing..." # ⚙️ or 🔧 or [*]
echo "$EMOJI_SUCCESS Done!" # ✅ (works everywhere)| Function | Description |
|---|---|
ui_box |
Styled box with rounded border |
ui_confirm |
Yes/No confirmation dialog |
ui_choose |
Single choice selection |
ui_choose_multi |
Multi-choice selection |
ui_choose_limit N |
Select up to N items |
ui_input |
Single-line text input |
ui_password |
Password input |
ui_write |
Multi-line text input |
ui_filter |
Fuzzy filter from list |
ui_file |
File picker |
ui_dir |
Directory picker |
ui_table |
Interactive table display |
ui_pager |
Scrollable text viewer |
ui_format |
Render markdown |
ui_format_code |
Syntax highlight code |
ui_spin |
Spinner while command runs |
ui_spin_type TYPE |
Spinner with type (dot, moon, globe, etc.) |
ui_join_h / ui_join_v |
Join text horizontally/vertically |
| Function | Description |
|---|---|
log_info |
Info level log |
log_warn |
Warning level log |
log_error |
Error level log |
log_debug |
Debug level (when VERBOSE=true) |
log_structured |
Key-value structured logging |
log_fatal |
Fatal error (exits script) |
funny_gums/
├── funny_gums.sh # Entry point - sources all modules
├── lib/
│ ├── core/ # Foundational utilities
│ │ ├── term/ # Colors, cursor, terminal
│ │ ├── text/ # Visual width, emojis
│ │ └── sh/ # Logging, sudo, deps
│ ├── ui/ # Visualization widgets
│ │ ├── layout/ # Core formatting, boxes
│ │ ├── widgets/ # Gauges, tables, spinners
│ │ └── interaction/ # Inputs, fuzzy select
│ ├── mod/ # Domain-specific modules
│ │ ├── hw/ # CPU, GPU, RAM, Sensors
│ │ ├── os/ # power, lspci, dmidecode
│ │ ├── storage/ # smartctl, hdparm
│ │ └── net/ # network info/ui
│ └── app/ # Application logic (Dashboard)
├── examples/ # Example scripts
└── tests/ # Test suite
./tests/run_tests.sh # Run all tests
./tests/run_tests.sh test_ui.sh # Run specific testFunny Gums includes proper handling for VS16 (Variation Selector 16) emojis like ⚙️,
source lib/core/text/text.sh
detect_terminal_mode # Detects "modern" or "legacy"
visual_width "Hello ⚙️" # Returns: 8 (5 + 1 + 2, VS16 is zero-width)
pad_visual "✅ Done" 15 # Pads to visual width 15Full support: Kitty, WezTerm, iTerm, Alacritty, Ghostty. Compatible (auto-fallback): GNOME Terminal, Tilix, VS Code
This library is powered by gum, part of the excellent Charm ecosystem of Go-based terminal tools:
- gum - A tool for glamorous shell scripts
- bubbletea - TUI framework for Go
- lipgloss - Style definitions for terminal apps
- bubbles - TUI components for bubbletea
If you work with Python, check out StyledConsole - a modern Python library for elegant terminal output with rich formatting, tables, panels, and gradients. It's like Funny Gums' sophisticated cousin for Python! 🐍✨
If you find Funny Gums useful, consider supporting its development:
| Platform | Link |
|---|---|
| GitHub Sponsors | github.com/sponsors/ksokolowski |
| Ko-fi | ko-fi.com/styledconsole |
Your support helps maintain both Funny Gums and StyledConsole!
Apache License 2.0 - see LICENSE for details.

