https://github.com/simeg/bash-cli-spinners
🌈 Bash/Zsh spinners for scripts and terminal
https://github.com/simeg/bash-cli-spinners
bash cli loader spinner zsh
Last synced: 2 months ago
JSON representation
🌈 Bash/Zsh spinners for scripts and terminal
- Host: GitHub
- URL: https://github.com/simeg/bash-cli-spinners
- Owner: simeg
- License: mit
- Created: 2025-08-20T17:49:25.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-24T10:50:58.000Z (10 months ago)
- Last Synced: 2025-08-24T13:46:27.609Z (10 months ago)
- Topics: bash, cli, loader, spinner, zsh
- Language: Shell
- Homepage: https://simeg.github.io/bash-cli-spinners/
- Size: 53.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# bash-cli-spinners [](https://github.com/simeg/bash-cli-spinners/actions/workflows/ci.yml)
> +80 spinners for use in the terminal
A bash/zsh cli spinner library **heavily inspired** by
[cli-spinners](https://github.com/sindresorhus/cli-spinners).
**🌐 View Live Demo of all spinners 🌐**
## Features
- **+80 spinners** from the [`cli-spinners`](https://github.com/sindresorhus/cli-spinners) package
- **JSON-based** - Easy to extend and maintain
- **Color support** - 14 different colors available
- **Two modes** - Show for duration or run with command
- **Clean output** - Proper cursor management and cleanup
- **Web gallery** - Interactive browser interface to preview all spinners
## Requirements
- `bash` 4.0+
- `jq` for JSON parsing
- `bc` for precise timing calculations
Install requirements:
```bash
# macOS
brew install jq bc
# Ubuntu/Debian
sudo apt install jq bc
```
## Quick Start
```bash
# List all available spinners
./spinner.sh list
# Show a spinner for 5 seconds
./spinner.sh show dots 5 "Loading data" blue
# Run a command with a spinner
./spinner.sh run pong "Installing packages" bright_green sleep 10
```
## Usage
### Basic Usage
```bash
./spinner.sh show [message] [color]
./spinner.sh run [message] [color]
```
### Examples
```bash
# Simple 3-second dots spinner
./spinner.sh show dots 3
# Pong game with custom message and color
./spinner.sh show pong 5 "Playing pong!" bright_green
# Weather spinner while downloading
./spinner.sh run weather "Downloading files" cyan curl -O https://example.com/file.zip
# Material design spinner while compiling
./spinner.sh run material "Compiling project" bright_blue make build
```
## Available Colors
### Basic Colors
      
### Bright Colors
      
## Installation
### For Use in Your Own Scripts
To integrate this spinner library into your own bash/zsh scripts, you need both
core files:
1. **Download the required files:**
```bash
# Download spinner engine
curl -O https://raw.githubusercontent.com/simeg/bash-cli-spinners/main/spinner.sh
# Download spinners database
curl -O https://raw.githubusercontent.com/simeg/bash-cli-spinners/main/spinners.json
```
2. **Make spinner.sh executable:**
```bash
chmod +x spinner.sh
```
3. **Use in your scripts:**
```bash
#!/usr/bin/env bash
set -euo pipefail
# Bring spinner functions into *this* shell
source ./spinner.sh
my_function() {
# your real logic here
sleep 10
}
# Run a finite task with a spinner
run_with_spinner "pong" "Installing" "cyan" my_function
# Or pass a normal command directly (no function needed)
run_with_spinner "dots" "Building assets" "blue" npm run build
```
## Architecture
### JSON Structure
Each spinner in `spinners.json` follows this format:
```json
{
"spinner_name": {
"interval": 80,
"frames": ["frame1", "frame2", "frame3"]
}
}
```
- `interval`: Time between frames in milliseconds
- `frames`: Array of strings/characters to display
## Related
- [cli-spinners](https://github.com/sindresorhus/cli-spinners)