runstep

A beautiful Bash utility for running step-based commands with spinners, progress tracking, and clean terminal output.

What is this?

runstep lets you execute shell commands as steps with visual feedback:

• ⏳ Animated spinners while commands run
• ✅ Success indicators
• ❌ Failure indicators
• 🎯 Step counters ([2/5])
• 🎨 Colored output
• 🧠 Optional failure handling
• 🔐 Automatic interactive mode for sudo

Perfect for installation scripts, setup wizards, bootstrap CLIs, dev environment provisioning, and CI helper tools.

Features

• Lightweight - Pure Bash, no dependencies
• Smart sudo detection - Automatically switches to interactive mode
• Async-safe - Handles background processes cleanly
• Clean UI - Professional terminal output
• Cross-platform - Works on macOS & Linux

Installation

Global Installation (Recommended)

npm install -g runstep

Project Installation

npm install runstep

As a Dependency

npm install --save runstep
# or
yarn add runstep
# or
pnpm add runstep

Usage

runstep can be used in three ways, depending on your needs:

Method 1: CLI Tool (Global Install)

Install globally and use as a command-line tool:

# Install globally
npm install -g runstep

# Use directly
runstep "Installing dependencies" false npm install

Syntax

runstep <message> <allow_failure> <command...>

Parameters:

• message - Description shown during execution
• allow_failure - true to continue on error, false to exit on error
• command... - The command to execute

Examples

# Update system packages
runstep "Updating system" false sudo apt update

# Allow failures
runstep "Optional cleanup" true rm -rf temp/

# Complex commands
runstep "Deploying app" false bash -c "npm run build && npm run deploy"

Method 2: Using npx (No Global Install)

Run without installing globally:

npx runstep "Building project" false npm run build

Note: Using npx in scripts works for single commands, but spawns a new process each time. For multi-step workflows with step counters, use Method 3 (sourcing the library).

Method 3: Source as Library (Recommended for Multi-Step Scripts)

For complex installation scripts or multi-step workflows, source the library directly. This is the most powerful method and avoids the common "command not found" issue.

The Problem with Direct Sourcing

If you try to source runstep.sh directly after installing via npm, you'll get errors:

# ❌ This DOESN'T work
source runstep.sh  # Error: runstep.sh: No such file or directory

This fails because npm installs the library in node_modules/runstep/lib/runstep.sh, not in your current directory.

The Solution: Proper Sourcing

There are two clean approaches:

Option A: Source from npm root (works with local installs)

#!/usr/bin/env bash

# Source from node_modules
source "$(npm root)/runstep/lib/runstep.sh"

# Define total steps
TOTAL_STEPS=4

# Run your steps
perform_step "Checking prerequisites" false command -v curl
perform_step "Updating packages" false sudo apt update
perform_step "Installing curl" false sudo apt install -y curl
perform_step "Cleanup" true rm -rf /tmp/temp-files

Option B: Source from global install

#!/usr/bin/env bash

# Source from global npm installation
source "$(npm root -g)/runstep/lib/runstep.sh"

TOTAL_STEPS=3
perform_step "Installing dependencies" false npm install
perform_step "Building project" false npm run build
perform_step "Running tests" false npm test

For Portable Scripts (No npm Dependency)

If you want your scripts to work without requiring users to install runstep via npm, copy lib/runstep.sh directly into your project:

your-project/
├── bin/
│   └── setup.sh
└── lib/
    └── runstep.sh

Then use relative paths:

#!/usr/bin/env bash

# Resolve script directory
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Source relative to script location
source "$SCRIPT_DIR/../lib/runstep.sh"

TOTAL_STEPS=3
perform_step "Step 1" false echo "Starting"
perform_step "Step 2" false sleep 1
perform_step "Step 3" true echo "Complete"

This approach:

• ✅ Works without npm/npx
• ✅ No global installation required
• ✅ Fully portable and self-contained
• ✅ Can be committed to git
• ✅ Works in CI/CD pipelines

API Reference

perform_step

Executes a command with spinner animation and status reporting.

perform_step <message> <allow_failure> <command...>

Parameters

| Name | Type | Description | |------|------|-------------| | message | string | Text displayed while the command runs | | allow_failure | boolean | true = continue on errorfalse = exit on error | | command... | string[] | The shell command to execute |

Behavior

• Sudo commands: Runs interactively (no spinner) to allow password input
• Regular commands: Shows animated spinner and redirects output
• Exit codes: Preserves command exit codes for error handling
• Visual feedback: Shows ✓ for success, ✗ for failure

Environment Variables

TOTAL_STEPS

Set this variable to enable step counters:

TOTAL_STEPS=5

This displays progress as [1/5], [2/5], etc.

Color Customization

You can override the default colors by redefining these variables:

GRAY='\033[38;5;240m'
GREEN='\033[0;32m'
RED='\033[0;31m'
WHITE='\033[38;5;15m'
MAGENTA='\033[0;35m'
NC='\033[0m'  # No Color

Complete Example

Here's a full installation script using runstep:

#!/usr/bin/env bash

# Source runstep (adjust path based on installation)
source "$(npm root -g)/runstep/lib/runstep.sh"

TOTAL_STEPS=6

echo "🚀 Setting up development environment..."
echo ""

perform_step "Checking for Homebrew" false command -v brew
perform_step "Updating Homebrew" false brew update
perform_step "Installing Node.js" false brew install node
perform_step "Installing dependencies" false npm install
perform_step "Building project" false npm run build
perform_step "Running tests" true npm test

echo ""
echo "✨ Setup complete!"

Why runstep?

Most spinner libraries are language-specific, dependency-heavy, or overly complex. runstep is different:

| Feature | runstep | Others | |---------|---------|--------| | Pure Bash | ✅ | ❌ | | Zero dependencies | ✅ | ❌ | | Works everywhere | ✅ | ❌ | | Copy-paste friendly | ✅ | ❌ | | npm installable | ✅ | ❌ |

Troubleshooting

"command not found" Error

Problem: You get runstep: command not found when trying to use it.

Solutions:

1. If using as CLI: Ensure it's installed globally

   npm install -g runstep
   # Verify installation
   which runstep

2. If using in scripts: Use npx instead

   npx runstep "Test" false echo "works"

3. Check your PATH includes npm bin directory:

   npm bin -g  # Should be in your PATH

"No such file or directory" When Sourcing

Problem: You get runstep.sh: No such file or directory when trying to source.

# ❌ This fails
source runstep.sh

Why it fails: After npm install, the library is in node_modules/runstep/lib/runstep.sh, not in your current directory.

Solutions:

For local npm install:

# ✅ Use npm root to find the correct path
source "$(npm root)/runstep/lib/runstep.sh"

For global npm install:

# ✅ Use global npm root
source "$(npm root -g)/runstep/lib/runstep.sh"

For portable scripts (no npm required):

1. Copy lib/runstep.sh into your project
2. Source it using relative paths:

   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
   source "$SCRIPT_DIR/../lib/runstep.sh"

"perform_step: command not found"

Problem: After sourcing, you get perform_step: command not found.

Cause: The library wasn't sourced correctly (see "No such file or directory" above).

Solution: Verify the sourcing path is correct:

# Check if file exists before sourcing
LIB_PATH="$(npm root)/runstep/lib/runstep.sh"
if [ ! -f "$LIB_PATH" ]; then
  echo "Error: runstep library not found at $LIB_PATH"
  exit 1
fi
source "$LIB_PATH"

Step Counters Not Working with npx

Problem: When using npx runstep multiple times, step numbers don't increment.

Why: Each npx call spawns a new process with its own state.

Solution: Use the library sourcing method for multi-step workflows:

#!/usr/bin/env bash

source "$(npm root)/runstep/lib/runstep.sh"

TOTAL_STEPS=3
perform_step "Step 1" false echo "First"
perform_step "Step 2" false echo "Second"  # Shows [2/3]
perform_step "Step 3" false echo "Third"   # Shows [3/3]

Best Practices by Use Case

| Use Case | Recommended Method | |----------|-------------------| | Single command execution | npx runstep or global CLI | | Multi-step installation scripts | Source the library from npm | | Portable scripts (no npm) | Copy library into project, use relative paths | | CI/CD pipelines | Global install or source from npm | | Quick one-off tasks | npx runstep |

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Humayun Kabir

Links

• npm Package
• GitHub Repository
• Issue Tracker

Built with ❤️ for the Bash community