Ruby-progress

Gem Version License: MIT Ruby

A collection of Ruby progress indicator projects: Ripple, Worm, Twirl, and Fill. All provide animated terminal progress indicators with different visual styles and features.

Quick Start

Install the gem:

gem install ruby-progress
Run in iTerm

Use the unified interface:

prg worm --message 'Processing data' --style blocks --checkmark
Run in iTerm
prg ripple 'Loading...' --style rainbow --speed fast
Run in iTerm
prg twirl --message 'Working...' --style dots --speed fast
Run in iTerm

Unified Interface

The gem provides a unified prg command that supports all progress indicators through subcommands. Run commands with progress animation:

prg worm --command 'sleep 5' --success 'Completed!' --error 'Failed!' --checkmark
Run in iTerm
prg ripple 'Building...' --command 'make build' --success 'Build complete!' --stdout
Run in iTerm
prg twirl --command 'npm install' --message 'Installing packages' --style arc
Run in iTerm

See the README for more CLI examples

Ripple

Sophisticated text animation library that creates ripple effects across text strings in the terminal. Supports various animation modes including bidirectional movement and rainbow colors.

Key Features:

  • Text ripple animations with customizable speed and direction
  • Style system supporting rainbow colors and inverse highlighting
  • Multiple animation formats: forward-only, bidirectional
  • Command execution with animated progress display

Basic text animation:

prg ripple 'Loading...'
Run in iTerm

With style options:

prg ripple 'Processing Data' --speed fast --style rainbow --direction bidirectional
Run in iTerm

Run a command with progress animation:

prg ripple 'Installing packages' --command 'sleep 5' --success 'Installation complete!' --checkmark
Run in iTerm

See the README for more Ripple CLI examples

Twirl

Lightweight spinner animation system providing over 35 different spinner styles for terminal progress indication. Perfect for showing indefinite progress during command execution.

Key Features:

  • 35+ spinner styles including dots, arrows, blocks, and geometric patterns
  • Flexible speed control (1-10 scale or named speeds)
  • Command execution with animated progress display
  • Daemon mode for background progress indication

Basic spinner animation:

prg twirl --message 'Processing...' --style dots
Run in iTerm

With command execution:

prg twirl --command 'npm install' --message 'Installing' --style arc
Run in iTerm

Different spinner styles:

prg twirl --message 'Working' --style arrows --speed fast
Run in iTerm

See the README for more Twirl CLI examples

Worm

Clean, Unicode-based progress indicator that creates a ripple effect using combining characters. Designed for running commands with visual progress feedback.

Key Features:

  • Ripple wave animation using Unicode characters
  • Multiple visual styles (circles, blocks, geometric)
  • Configurable speed and customizable length
  • Command execution with progress indication
  • Custom styles with 3-character patterns

Run indefinitely without a command:

prg worm --message 'Loading...' --speed fast --style circles
Run in iTerm

Run a command with progress animation:

prg worm --command 'sleep 5' --message 'Installing' --success 'Done!'
Run in iTerm

Custom animations with 3-character patterns:

prg worm --message 'Custom style' --style 'custom=_-=' --command 'sleep 2'
Run in iTerm
prg worm --message 'Emoji worm!' --style 'custom=🟦🟨🟥' --success 'Complete!'
Run in iTerm

See the README for more Worm CLI examples

Background Mode

All progress indicators support daemon mode for background tasks:

Start a background indicator:

prg worm --daemon-as mytask --message 'Background processing'
Run in iTerm

Stop it later with a message:

prg job stop --daemon-name mytask --message 'Task complete!' --checkmark
Run in iTerm

See the README for more background mode examples

Library Usage

The entire ruby-progress gem can be installed in your Gemfile and used as a library. This offers the ability to run a sequence of commands as a block passed to an indicator and offers elegant control of the indicators.

See the README for library usage examples

Installation

As a gem (recommended):

gem install ruby-progress
Run in iTerm

From source:

git clone https://github.com/ttscoff/ruby-progress.git
cd ruby-progress
bundle install
bundle exec rake build
gem install pkg/ruby-progress-*.gem

See the README for more installation options

Requirements

  • Ruby 2.7 or higher
  • Terminal with Unicode support (for Worm)
  • ANSI color support (for Ripple rainbow effects)

See the README for complete documentation

Speaking of ruby-progress…

Related Projects