stream-stepper

README

StreamStepper

A Go-based CLI tool that parses shell command output to render it formatted in a beautiful terminal UI (TUI) with a dynamic progress bar.

StreamStepper intercepts stdout and stderr from your scripts. It listens for specific trigger strings to:

• increment a progress bar to follow the progress of the process
• extract status messages to report what is doing
• colorize messages depending on whether they are in stdout, stdin or flagged with a specific sequence of characters
• indent logs for better reading

while keeping the raw logs available in a scrollable view.

Without StreamStepper

With StreamStepper

Installation

Ensure you have Go installed, then launch this command:

go install github.com/pivaldi/stream-stepper@latest

How It Works

StreamStepper scans text line-by-line. If a line beginnings by the trigger flag (default: ==>), three things happen:

1. The progress bar increments by 1 step.
2. The line is colorized in blue.
3. Any text following the flag on that same line is displayed as the current status message in the bottom panel.

All other output is printed indented by one tabulation in the main scrolling window.

Usage

Command-Line Flags

• --steps (Required): Total number of steps required to reach 100%.
• --flag (Optional): The string trigger to look for. Default is ==>.
• --tagged (Optional): Boolean flag to read from stdin expecting [OUT] and [ERR] prefixes.
• --err-fifo (Optional): Path to a named pipe to read stderr from.
• --pb-width (Optional): The progress-bar width. Default is 40 spaces.
• --processor (Optional): The line processor. Can be change to stbash to support bash-stepper. See the file ./examples/stbash.sh for an example using bash-stepper.

Operating Modes

StreamStepper supports three ways to route your data:

1. Exec Mode (Default)

Pass the command as an argument. StreamStepper executes it as a child process and handles stdout and stderr automatically.

stream-stepper --steps=7 ./examples/deploy.sh

2. Standard Pipe Mode

Pipe data directly into StreamStepper. Note: as pipe redirect stderr to stdout, StreamStepper can not capture errors with this usage.

./examples/deploy.sh 2>&1 | stream-stepper --steps=7

3. Tagged Pipe Mode (Separated stdout/stderr)

If you want to pipe data but keep stderr visually distinct (rendered in red), you can use Bash to tag the streams before they enter the UI. In this case as sed blocks buffering, the parsing is not realtime.

{ ./examples/deploy.sh 2>&1 1>&3 | sed 's/^/[ERR] /' >&2; } 3>&1 1>&2 | sed 's/^/[OUT] /' | stream-stepper --steps=7 --taggedA

To fix unbuffered sed using GNU sed:

{ stdbuf -oL -eL ./examples/deploy.sh 2>&1 1>&3 | \
    sed -u 's/^/[ERR] /' >&2; } 3>&1 1>&2 | \
    sed -u 's/^/[OUT] /' | \
    stream-stepper --steps=7 --tagged

4. FIFO Mode (Named Pipes)

Route stderr through a named pipe, and stdout through the standard pipe.

mkfifo err_pipe && {
    ./examples/deploy.sh 2> err_pipe | stream-stepper --steps=7 --err-fifo="err_pipe"
    rm err_pipe
}

Try the Examples

Clone the repo and try the example script:

• go run . --steps 7 ./examples/deploy.sh
• ERROR=true go run . --steps 7 ./examples/deploy.sh
• EXIT=true go run . --steps 7 ./examples/deploy.sh

Dependencies

• tview - Terminal UI library
• tcell - Terminal handling