bash-cli-spinners [](https://github.com/simeg/bash-cli-spinners/actions/workflows/ci.yml)

August 26, 2025 · View on GitHub

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

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

Make spinner.sh executable:
```
chmod +x spinner.sh
```

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

cli-spinners