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

$3

``bash
npm install -g runstep
`

$3

`bash
npm install runstep
`

$3

`bash
npm install --save runstep


or

yarn add runstep

or

pnpm add runstep
`

---

Usage

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

$3

Install globally and use as a command-line tool:

`bash


Install globally

npm install -g runstep

Use directly

runstep "Installing dependencies" false npm install
`

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

Allow 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 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

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

`bash
#!/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

$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 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

$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 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]
`

---

$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` |

---

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