zsp

zSplash

v0.8.0 · Pure Go CLI

Terminal text formatting, Unicode block banners, 66ch typographic prose, status badges, TSV tables, async spinners, and progress bars for Zsh and shell scripts.

INSTALL (HOMEBREW)brew install acorrow/tap/zsplash
Installs both zsplash and the zsp shorthand
macOS / Linux / WindowsGo Standard Library OnlyCGO_ENABLED=0Sub-10ms Startup20 Built-In ThemesMIT License

Core Capabilities

01

Block Banners & Boxes

3-row block, 2-row compact, and 3-row box-drawing headlines (zsp banner) plus word-wrapped callout frames (zsp box) with rounded, double, heavy, and ASCII borders.

02

66ch Typographic Prose

High-readability terminal prose (zsp prose / zsp read) capped at 66 columns with inline code chips, hanging bullets, and --tip, --note, and --warn callout rails.

03

Status Pill Badges

High-contrast inverted TrueColor status pills (zsp ok, zsp info, zsp warn, zsp err) with right-aligned dot-leader --meta telemetry.

04

Key-Value Cards & TSV Tables

Framed dot-leader summary cards (zsp kv) and auto-aligned TSV tables (zsp tsv) with right-aligned numeric columns and proportional narrow-terminal truncation.

05

Crash-Proof /dev/tty Spinners

zsp spin animates on /dev/tty so stdout stays clean for $(...) capture, forwards signals cleanly, and always restores the terminal cursor on SIGINT or SIGTERM.

06

Fractional Progress Bars

In-place progress bars (zsp bar) and stdin stream line counters (zsp progress) with percentage and item completion telemetry.

07

Terminal Resize Reactivity

Queries /dev/tty column width (ZSPLASH_WIDTH, COLUMNS) dynamically so boxes soft-wrap and active spinners/bars resize on every frame without ghost lines.

08

Script-Safe Sanitization

Strips control characters and Unicode bidi/format sequences by default, supports double-dash ("--") untrusted argument boundaries, and honors NO_COLOR and TERM=dumb.

Zsh Usage Examples

Banners, Badges & Layout

# Render a styled block banner with subtitle
zsp banner "DEPLOY" --font block --frame --sub "Production Release"

# Phase divider in multistage automation
zsp step 1 3 "Verifying Infrastructure"

# High-contrast status pill with dot-leader telemetry
zsp ok "Database schema verified" --meta "42ms"

# Framed callout box fitted to terminal width
zsp box "Build complete. Artifacts published." --title "CI/CD" --border rounded

Prose, Tables, Spinners & Bars

# High-readability 66ch prose with tip callout rail
zsp prose --eyebrow "GUIDE" --title "Configuration" \
  "Configure terminal width via ZSPLASH_WIDTH." \
  --tip "Set theme persistently with: zsp theme snes"

# Auto-aligned TSV table with numeric right-alignment
printf "SERVICE\tSTATUS\tLATENCY\napi\thealthy\t12ms\nworker\tready\t4ms\n" | zsp tsv -H

# Crash-proof spinner keeping stdout clean for variable capture
SHA=$(zsp spin "Resolving commit" --persist --duration 600; git rev-parse --short HEAD)

# Fractional progress bar with in-place redraw
for i in {1..50}; do zsp bar $i 50 "Syncing files" --in-place; sleep 0.02; done

CLI Surface Reference

Command (Aliases)SyntaxKey FlagsDescription
banner(big)zsp banner <text> [flags]-f, --font block|compact|line; -c, --color; -g, --gradient; --sub <t>; --frame3-row block, 2-row compact, or 3-row box-drawing headline banner with TrueColor gradients.
box(default)zsp box <text> [flags]-t, --title; --footer; -b, --border rounded|double|heavy|ascii; -w, --widthWord-wrapped callout box dynamically fitted to terminal column width.
prose(read)zsp prose [flags] [text...]-e, --eyebrow; -t, --title; --tip <t>; --note <t>; --warn <t>; -w, --widthHigh-readability 66-column prose with inline code highlighting and callout rails.
ok / info / warn / err(pass, fail)zsp ok <msg> [--meta <detail>]-m, --meta <detail>Inverted TrueColor status pills with right-aligned dot-leader telemetry.
stepzsp step <curr> <total> <title>-c, --color; -g, --gradientFull-width phase divider line and step counter for multistage automation scripts.
rule(hr)zsp rule [label] [flags]-c, --color; -g, --gradient; -w, --widthHorizontal divider rule with optional centered label and TrueColor accents.
kv(card)zsp kv [flags] <k1> <v1> [<k2> <v2>...]-t, --title; -c, --color; -g, --gradientFramed key-value summary card with aligned dot-leaders.
tsv(table)zsp tsv [flags] [rows...]-H, --header; --headers <cols>; -f, --file; -a, --align; --compactAuto-aligned TSV table from arguments, file, or stdin with numeric alignment.
tree(list)zsp tree [flags] <item1> [<item2>...]-t, --title; -c, --colorUnicode checklist and hierarchical tree representation.
cmdzsp cmd <shell command>(none)Shell command preview with colored gutter indicator and token syntax accents.
codezsp code [flags] <line1> [<line2>...]-t, --titleFramed multi-line code block for shell script snippets and configuration files.
stylezsp style <text> [flags]--fg <c>; --bg <c>; -g, --gradient; -b, --bold; -i, --italic; -u, --underlineInline styled text with arbitrary foreground, background, and gradient spans.
spinzsp spin [title] [flags] [child-cmd]-s, --style dots|pulse|meter|line; -p, --persist; --static; --stdin; -d, --durationCrash-proof /dev/tty spinner that keeps stdout clean for variable capture.
barzsp bar <curr> <total> [label] [flags]-r, --in-place; -w, --width; -c, --color; -g, --gradientHalf-cell Unicode progress bar with percentage and current/total metrics.
progress<cmd> | zsp progress [flags]--total <n>; -t, --title; -c, --color; -g, --gradientStream line counter from stdin rendering live progress telemetry on /dev/tty.
themes / themezsp themes | zsp theme [<name>](none)Inspect 20 built-in palettes or persist default theme in config.json.
configzsp config [list | set <k> <v> | reset | path](none)Inspect, update, or reset persistent CLI configuration in ~/.config/zsplash/.
demozsp demo [--theme <name>]-T, --theme <name>Interactive visual showcase exercising every format engine and palette.
help / docs(manual, schema)zsp help [<cmd>] | zsp docs [flags]-j, --json; --markdownBuilt-in command manual, full Markdown documentation, and JSON CLI schema.

Built-In Color Palettes

zSplash includes 20 curated TrueColor palettes designed for legibility on dark and retro terminal emulators. Themes can be selected per-command with -T, --theme or set persistently with zsp theme <name>.

modernnessnesxboxhalogameboypipboydraculacatppuccinnordgruvboxtokyonightmonokaisolarizedrosepineeverforestkanagawasynthwaveindustrialamber

Technical Stack

LanguageGo (100% Standard Library, Zero External Dependencies)
Binary TargetCGO_ENABLED=0 Static Binary
Binaries Installedzsplash and zsp symlink
Configuration~/.config/zsplash/config.json
Documentation EngineBuilt-in Markdown manual (zsp docs) and JSON schema (zsp docs --json)
LicenseMIT License