๐ญ ShellCandy
Beautiful Terminal UIs for Shell Scripts
A comprehensive framework for creating stunning terminal interfaces in pure Bash
Quick Start โข
Features โข
Installation โข
Examples โข
Documentation
๐ฏ What is ShellCandy?
ShellCandy transforms ordinary shell scripts into beautiful, interactive terminal applications. With 9 powerful modules and 60+ functions, you can create professional UIs with:
โจ Interactive menus with keyboard navigation
๐ Data visualization with charts and sparklines
๐ Auto-sizing tables with perfect alignment
๐จ Rich colors (256-color, RGB, themes)
โก Progress indicators (bars, spinners, gauges)
๐ Interactive forms with validation
๐ฏ Zero dependencies - Pure Bash 4.0+
๐ Quick Start
Install
curl -fsSL https://raw.githubusercontent.com/NickCrew/shellcandy/main/install.sh | bash
Your First Script
#!/usr/bin/env bash
source ~/.shellcandy/lib/shellcandy.sh
# Beautiful boxes
box_success "Welcome!" \
"ShellCandy makes terminals beautiful" \
"๐จ Colors ๐ Charts ๐ฏ Menus โก Progress"
# Data visualization
declare -a data=(45 52 68 73 81 76 84 92)
echo "Trend: $(sc_sparkline data) ๐"
# Progress bar
sc_progress_bar 75 100 "Processing"
โจ Features
9 Complete Modules
| Module |
Description |
| colors |
256-color, RGB, themes, gradients |
| logging |
Multi-level logging with file output |
| progress |
Spinners, bars, ETA calculations |
| icons |
50+ status symbols and emojis |
| boxes |
Perfect alignment with ANSI/emoji support |
| tables |
Auto-sizing, CSV import, formatting |
| prompts |
Interactive forms with validation |
| menus |
Keyboard navigation, nested menus |
| charts |
Sparklines, bar charts, gauges, histograms |
ย ย
๐ฆ Installation
One-Line Install (Recommended)
curl -fsSL https://raw.githubusercontent.com/NickCrew/shellcandy/main/install.sh | bash
Manual Install
git clone https://github.com/NickCrew/shellcandy.git ~/.shellcandy
echo 'export SHELLCANDY_HOME="$HOME/.shellcandy"' >> ~/.bashrc
echo 'source $SHELLCANDY_HOME/lib/shellcandy.sh' >> ~/.bashrc
source ~/.bashrc
๐ Examples
Interactive Menu
#!/usr/bin/env bash
source ~/.shellcandy/lib/shellcandy.sh
sc_menu_create "Main Menu"
sc_menu_add "Deploy" "deploy_app" "true" "d"
sc_menu_add "Status" "show_status" "true" "s"
sc_menu_add "Logs" "view_logs" "true" "l"
sc_menu_add "Exit" "exit" "true" "q"
sc_menu_show
Data Visualization
#!/usr/bin/env bash
source ~/.shellcandy/lib/shellcandy.sh
# System metrics
declare -a cpu=(30 35 42 45 50 48 52)
sc_gauge 52 100 "CPU Usage" 40
echo "Trend: $(sc_sparkline cpu)"
# Table
sc_table_create "rounded"
sc_table_header "Service" "Status" "CPU"
sc_table_row "Web" "โ OK" "23%"
sc_table_row "DB" "โ OK" "45%"
sc_table_render
ย ย
Color Themes
sc_theme_load ships default, dark, light, solarized, nord, dracula, and unafy (Unanet's design system). A theme only recolors what a script explicitly draws with $SC_THEME_BG/$SC_THEME_FG/$SC_THEME_PRIMARY/$SC_THEME_ACCENT; semantic widgets like box_success or bar-chart colors stay red/yellow/green by design.
#!/usr/bin/env bash
source ~/.shellcandy/lib/shellcandy.sh
sc_theme_load unafy
echo -e "${SC_THEME_PRIMARY}${SC_BOLD}CRM Release Console${SC_RESET}"
box "Environments" --color="$SC_THEME_PRIMARY" "int-crm-01: v26.8.0 (healthy)"
echo -e "${SC_THEME_ACCENT}Promoting to stage...${SC_RESET}"
๐ Documentation
โก Performance
ShellCandy is highly optimized:
| Metric |
Performance |
Status |
| Core functions |
40-70ยตs/call |
โ
|
| Box rendering |
2-4ms |
โ
|
| Table (10 rows) |
15-25ms |
โ
|
| Sparklines |
1-2ms |
โ
|
Run tests:
shellcandy-validate # 68 tests
shellcandy-benchmark # 13 benchmarks
๐ค Contributing
Contributions welcome! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create feature branch:
git checkout -b feature/amazing-feature
- Make changes and test:
./lib/validate.sh
- Commit:
git commit -m 'Add amazing feature'
- Push:
git push origin feature/amazing-feature
- Open a Pull Request
๐ Project Stats
- 9 modules with 60+ functions
- 10,100 lines of code
- 68 validation tests (100% passing)
- 13 performance benchmarks
- Zero dependencies
- Pure Bash 4.0+
๐ License
MIT License - See LICENSE for details
Copyright (c) 2025 Nicholas Crew Ferguson
๐ Links
Made with ๐ญ ShellCandy
Making terminals beautiful, one script at a time
โญ Star us on GitHub if you find ShellCandy useful!