bash-cli-spinners

+80 spinners for use in the terminal

A bash/zsh cli spinner library heavily inspired by cli-spinners.

🌐 View Live Demo of all spinners 🌐

Features

• +80 spinners from the 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:

# macOS
brew install jq bc

# Ubuntu/Debian
sudo apt install jq bc

Quick Start

# 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

./spinner.sh show <spinner_name> <duration> [message] [color]
./spinner.sh run <spinner_name> [message] [color] <command>

Examples

# 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:

   # 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:

   chmod +x spinner.sh

3. Use in your scripts:

   #!/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:

{
  "spinner_name": {
    "interval": 80,
    "frames": ["frame1", "frame2", "frame3"]
  }
}

• interval: Time between frames in milliseconds
• frames: Array of strings/characters to display

Related

• cli-spinners