zSplash
v0.8.0 · Pure Go CLITerminal text formatting, Unicode block banners, 66ch typographic prose, status badges, TSV tables, async spinners, and progress bars for Zsh and shell scripts.
brew install acorrow/tap/zsplashCore Capabilities
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.
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.
Status Pill Badges
High-contrast inverted TrueColor status pills (zsp ok, zsp info, zsp warn, zsp err) with right-aligned dot-leader --meta telemetry.
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.
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.
Fractional Progress Bars
In-place progress bars (zsp bar) and stdin stream line counters (zsp progress) with percentage and item completion telemetry.
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.
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; doneCLI Surface Reference
| Command (Aliases) | Syntax | Key Flags | Description |
|---|---|---|---|
| banner(big) | zsp banner <text> [flags] | -f, --font block|compact|line; -c, --color; -g, --gradient; --sub <t>; --frame | 3-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, --width | Word-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, --width | High-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. |
| step | zsp step <curr> <total> <title> | -c, --color; -g, --gradient | Full-width phase divider line and step counter for multistage automation scripts. |
| rule(hr) | zsp rule [label] [flags] | -c, --color; -g, --gradient; -w, --width | Horizontal divider rule with optional centered label and TrueColor accents. |
| kv(card) | zsp kv [flags] <k1> <v1> [<k2> <v2>...] | -t, --title; -c, --color; -g, --gradient | Framed key-value summary card with aligned dot-leaders. |
| tsv(table) | zsp tsv [flags] [rows...] | -H, --header; --headers <cols>; -f, --file; -a, --align; --compact | Auto-aligned TSV table from arguments, file, or stdin with numeric alignment. |
| tree(list) | zsp tree [flags] <item1> [<item2>...] | -t, --title; -c, --color | Unicode checklist and hierarchical tree representation. |
| cmd | zsp cmd <shell command> | (none) | Shell command preview with colored gutter indicator and token syntax accents. |
| code | zsp code [flags] <line1> [<line2>...] | -t, --title | Framed multi-line code block for shell script snippets and configuration files. |
| style | zsp style <text> [flags] | --fg <c>; --bg <c>; -g, --gradient; -b, --bold; -i, --italic; -u, --underline | Inline styled text with arbitrary foreground, background, and gradient spans. |
| spin | zsp spin [title] [flags] [child-cmd] | -s, --style dots|pulse|meter|line; -p, --persist; --static; --stdin; -d, --duration | Crash-proof /dev/tty spinner that keeps stdout clean for variable capture. |
| bar | zsp bar <curr> <total> [label] [flags] | -r, --in-place; -w, --width; -c, --color; -g, --gradient | Half-cell Unicode progress bar with percentage and current/total metrics. |
| progress | <cmd> | zsp progress [flags] | --total <n>; -t, --title; -c, --color; -g, --gradient | Stream line counter from stdin rendering live progress telemetry on /dev/tty. |
| themes / theme | zsp themes | zsp theme [<name>] | (none) | Inspect 20 built-in palettes or persist default theme in config.json. |
| config | zsp config [list | set <k> <v> | reset | path] | (none) | Inspect, update, or reset persistent CLI configuration in ~/.config/zsplash/. |
| demo | zsp 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; --markdown | Built-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>.
Technical Stack
| Language | Go (100% Standard Library, Zero External Dependencies) |
| Binary Target | CGO_ENABLED=0 Static Binary |
| Binaries Installed | zsplash and zsp symlink |
| Configuration | ~/.config/zsplash/config.json |
| Documentation Engine | Built-in Markdown manual (zsp docs) and JSON schema (zsp docs --json) |
| License | MIT License |