A pure-Bash lolcat replacement — UTF-8 safe, zero-dependency rainbow colouring with full argument parity

---

Screenshot

---

Features

• Zero external dependencies — pure Bash + a minimal Python 3 one-liner (present on every modern Linux/macOS)
• Full lolcat parity — -F freq, -p spread, -S seed, -G angle, -a animate, -d frames, -s fps, -i invert, -f force, -r header, -A ANSI preview
• Diagonal gradient — true 2D sin/cos angle projection; not just horizontal bands
• Shell integration — eval "$(bashcat --env)" exports BASHCAT_FG, BASHCAT_BG, pill vars, and helper functions into your shell session
• UTF-8 safe — splits on codepoints, not raw bytes; emoji and box-drawing characters colour correctly
• NO_COLOR aware — respects the spec; passes stdin through untouched when set
• TTY detection — auto-disables colour when piping unless -f is set

---

Installation

Recommended — one-line installer

curl -fsSL https://raw.githubusercontent.com/DitherZ/bashcat/main/install.sh | bash

The installer will:

1. Clone the repo to /tmp/bashcat-3.1.0/
2. Copy the bashcat binary to ~/.local/bin/ with rwxr-xr-x permissions
3. Append eval "$(bashcat --env)" to your ~/.zshrc
4. Clean up the temp clone automatically

Note: ~/.local/bin must be in your $PATH. Add export PATH="$HOME/.local/bin:$PATH" to your .zshrc if it isn't already.

---

Manual install

git clone https://github.com/DitherZ/bashcat.git
cp bashcat/bashcat ~/.local/bin/bashcat
chmod u+rwx,g+rx,o+rx ~/.local/bin/bashcat

Then add shell integration to your .zshrc:

# Bashcat Environment Variables
eval "$(bashcat --env)"

---

Source release

Download the v3.1.0 source archive and extract manually.

---

Uninstallation

The installer includes an --uninstall flag that removes the binary and strips the bashcat eval block from your .zshrc:

bash <(curl -fsSL https://raw.githubusercontent.com/DitherZ/bashcat/main/install.sh) --uninstall

Or if you have the script locally:

./install.sh --uninstall

This will:

1. Remove ~/.local/bin/bashcat
2. Strip the eval "$(bashcat --env)" line from ~/.zshrc

To manually uninstall:

rm ~/.local/bin/bashcat
# then remove the bashcat eval line from ~/.zshrc

---

Usage

bashcat [OPTIONS] [FILE ...]

Reads from FILE(s) or stdin when no file is given.

Option	Argument	Description	Default
-F	<freq>	Wave frequency multiplier	0.1
-p	<spread>	Characters per colour cycle	3.0
-S	<seed>	Hue seed (0 = random)	random
-G	<angle>	Gradient angle in degrees	random 0–359
-a	—	Animate (psychedelic mode)	off
-d	<frames>	Animation frame count	12
-s	<fps>	Animation speed in FPS	20.0
-i	—	Invert colours (colour on background)	off
-f	—	Force colour output (non-TTY safe)	off
-r	—	Print ==> filename <== header before each file	off
-A	—	ANSI preview: coloured output + raw escape dump	off
--env	—	Print eval-able shell definitions	—
-h	—	Show help	—

---

Examples

# Pipe any command output through bashcat
ls -la | bashcat

# Colourise a file
bashcat README.md

# Animate — psychedelic mode
cat myfile | bashcat -a -s 30

# Invert — colour on background
echo "hello world" | bashcat -i -f

# Force colour even in a non-TTY context (e.g. inside scripts)
echo "status: ok" | bashcat -f

# Fixed seed and angle for reproducible output
echo "deterministic" | bashcat -S 42 -G 45

---

Shell Integration

After running eval "$(bashcat --env)" (added automatically by the installer), the following are available in your shell session:

# Foreground colour from the current gradient
echo -e "${BASHCAT_FG}coloured text${RESET}"

# Background colour
echo -e "${BASHCAT_BG}highlighted text${RESET}"

# Per-character rainbow via pipe
echo "rainbow" | bashcat -f

# Alias: rcat — drop-in for bashcat
rcat myfile.txt

# Pill components (_PL, _PR, _SPL, _SPR, _GPL, _GPR)
# are exported for use in your own scripts

---

Requirements

• Bash 4.0+
• Python 3.6+ (stdlib only — math, sys, re, time)
• git (for the one-line installer only)

---

License

MIT — see LICENSE for details.

---

_{Made by DitherZ}