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


---
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.
---
* 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
---
``bash`
npm install -g runstep
`bash`
npm install runstep
`bash`
npm install --save runstepor
yarn add runstepor
pnpm add runstep
---
runstep can be used in three ways, depending on your needs:
Install globally and use as a command-line tool:
`bashInstall globally
npm install -g runstep
#### Syntax
`bash
runstep
`Parameters:
-
message - Description shown during execution
- allow_failure - true to continue on error, false to exit on error
- command... - The command to execute#### Examples
`bash
Update system packages
runstep "Updating system" false sudo apt updateAllow failures
runstep "Optional cleanup" true rm -rf temp/Complex commands
runstep "Deploying app" false bash -c "npm run build && npm run deploy"
`---
$3
Run without installing globally:
`bash
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).---
$3
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:`bash
ā 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)
`bash
#!/usr/bin/env bashSource from node_modules
source "$(npm root)/runstep/lib/runstep.sh"Define total steps
TOTAL_STEPS=4Run 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
`bash
#!/usr/bin/env bashSource 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:
`bash
#!/usr/bin/env bashResolve 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
$3
Executes a command with spinner animation and status reporting.
`bash
perform_step
`#### Parameters
| Name | Type | Description |
|------|------|-------------|
|
message | string | Text displayed while the command runs |
| allow_failure | boolean | true = continue on error
false = 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
$3
Set this variable to enable step counters:
`bash
TOTAL_STEPS=5
`This displays progress as
[1/5], [2/5], etc.$3
You can override the default colors by redefining these variables:
`bash
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:`bash
#!/usr/bin/env bashSource 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
$3
Problem: You get
runstep: command not found when trying to use it.Solutions:
1. If using as CLI: Ensure it's installed globally
`bash
npm install -g runstep
# Verify installation
which runstep
`2. If using in scripts: Use
npx instead
`bash
npx runstep "Test" false echo "works"
`3. Check your PATH includes npm bin directory:
`bash
npm bin -g # Should be in your PATH
`---
$3
Problem: You get
runstep.sh: No such file or directory when trying to source.`bash
ā 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:
`bash
ā
Use npm root to find the correct path
source "$(npm root)/runstep/lib/runstep.sh"
`For global npm install:
`bash
ā
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:
`bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/../lib/runstep.sh"
`---
$3
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:
`bash
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"
`---
$3
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:
`bash
#!/usr/bin/env bashsource "$(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]
`---
$3
| 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` |---
Contributions are welcome! Please feel free to submit a Pull Request.
---
MIT Ā© Humayun Kabir
---
- npm Package
- GitHub Repository
- Issue Tracker
---
Built with ā¤ļø for the Bash community