Ruinsay

A mischievous terminal creature that speaks your words

Spiritual successor to cowsay and fortune, built with Rust and modern terminal capabilities

Features • Installation • Usage • Ecosystem • Templates • Roadmap

Features

Signature Mascot - Meet the gremlin, critter's mischievous mascot with 7 moods
59 Animated Creatures - Every template has 6-9 animation frames + animated variants
True Color Support - Full RGB color support with automatic degradation to 256/16 colors
Rainbow Mode - Built-in lolcat-style colorful gradients
Streaming Mode - Live-updating output for tail -f and log watching
Command Execution - --exec and --watch for scripting integration
Built-in Fortune - No piping needed, fortunes are first-class citizens
Text Styling - Bold, italic, underline + custom colors and themes
Spinners & Progress - 44+ spinner animations + progress bars with braille/block/ASCII styles
Animation Engine - Text effects, particle systems, and scene composition with easing
Written in Rust - Fast, safe, and cross-platform
59 Builtin Templates - All classic cowsay creatures + new originals, fully animated
Template Variants - Same creature, different moods (dead cow, happy cat, etc.)
Expressive Commands - say, think, yell, whisper with matching bubble styles
Animation Support - Multi-frame animated creatures
Extensible - Create your own templates in TOML
Pipe Friendly - Works great with fortune, lolcat, and other Unix tools

Ecosystem

critter is available as a modular workspace with bindings for multiple languages:

Package	Description	Install
critter-cli	CLI binary	`cargo install critter-cli`
critter-core	Rust library	`critter-core = "0.5"`
critter-py	Python bindings	`pip install critter`
critter-wasm	WebAssembly	`npm install critter-wasm`
critter-lua	Lua/Neovim	Copy `libcritter.so`

Use from Python

import critter_py

# Quick usage
print(critter_py.say("Hello from Python!"))
print(critter_py.fortune())

# Object-oriented
c = critter_py.Critter("gremlin", variant="happy")
print(c.say("I'm happy!"))

Use from Rust

use critter_core::{Critter, FortuneCategory};

fn main() -> anyhow::Result<()> {
    let critter = Critter::new("gremlin")?.rainbow();
    
    println!("{}", critter.say("Hello from Rust!"));
    println!("{}", critter.fortune(FortuneCategory::Programming));
    
    Ok(())
}

Use in Browser (WASM)

import init, { Critter, say, fortune } from 'critter-wasm';

await init();

// Quick functions
document.body.innerHTML = `<pre>${say("Hello from WASM!")}</pre>`;

// Class-based
const gremlin = new Critter("gremlin");
console.log(gremlin.think("Running in browser..."));

Use in Neovim (Lua)

local critter = require("critter")

-- Dashboard header
local header = critter.say("Welcome back!")

-- Random fortune on startup
vim.api.nvim_create_autocmd("VimEnter", {
    callback = function()
        print(critter.fortune())
    end
})

Installation

Prebuilt Binaries

Download the latest release from GitHub Releases:

Platform	Architecture	Download
Linux	x86_64	`critter-x86_64-unknown-linux-gnu.tar.gz`
Linux	x86_64 (static)	`critter-x86_64-unknown-linux-musl.tar.gz`
Linux	ARM64	`critter-aarch64-unknown-linux-gnu.tar.gz`
macOS	x86_64	`critter-x86_64-apple-darwin.tar.gz`
macOS	Apple Silicon	`critter-aarch64-apple-darwin.tar.gz`
Windows	x86_64	`critter-x86_64-pc-windows-msvc.zip`

From Source

# Install via cargo
cargo install --git https://github.com/cd4u2b0z/critter

# Or clone and build
git clone https://github.com/cd4u2b0z/critter
cd critter
cargo build --release

Shell Completions

# Bash - add to ~/.bashrc
critter completions bash >> ~/.bashrc

# Zsh - add to ~/.zshrc (or use a completions dir)
critter completions zsh > ~/.zfunc/_critter

# Fish
critter completions fish > ~/.config/fish/completions/critter.fish

# PowerShell - add to $PROFILE
critter completions powershell >> $PROFILE

Usage

Basic Usage

# Say something (default gremlin mascot)
critter "Hello, World!"

# Think something (thought bubble)
critter think "Hmm, interesting..."

# Yell something (dramatic bubble)
critter yell "LOUD NOISES!"

# Whisper something (minimal bubble)
critter whisper "psst... over here"

# Pipe text through critter
echo "Hello, World!" | critter

# Use with fortune
fortune | critter

Templates

# List available templates
critter list

# Use a specific template
critter -t tux "Linux is great!"

# Use a template variant
critter -t cow -v dead "Oops..."
critter -t gremlin -v hacker "sudo rm -rf /"

# Preview a creature (no text)
critter show gremlin
critter show gremlin -v love

# List available variants for a template
critter variants gremlin

# Random template
fortune | critter random

# Random template with tag filter
fortune | critter random --tag animal

Cowsay Creatures (Animated!)

All 46 classic cowsay creatures are included — and they're all animated! Each has 6-9 frames of subtle animation:

# Classic cow with tail swishing
critter -t cow "Moo!"

# Tux the Linux penguin with flipper waving
critter -t tux "I use Arch btw"

# Stegosaurus with spines undulating  
critter -t stegosaurus "Look at my plates!"

# Vader with breathing/cape animation
critter -t vader "I am your father"

# Dragon breathing fire
critter -t dragon "🔥 Rawr!"

# Popular cowsay characters
critter -t beavis "Heh heh heh"
critter -t stimpy "Happy happy joy joy!"
critter -t ghostbusters "Who you gonna call?"
critter -t hellokitty "Kawaii!"

Quick Reference - All 69 Templates:

Category	Templates
Animals	`cow`, `dragon`, `elephant`, `fox`, `koala`, `moose`, `owl`, `sheep`, `turtle`, `bunny`, `cat`, `duck`, `kitty`, `parrot`, `penguin`, `turkey`, `alpaca`, `llama`, `blowfish`
Pop Culture	`vader`, `beavis`, `stimpy`, `ghostbusters`, `hellokitty`, `ren`, `kiss`, `daemon`
Classics	`tux`, `stegosaurus`, `ferris`, `gremlin`, `doge`, `sus`, `clippy`
Fantasy	`dragon`, `cthulhu`, `wizard`, `ghost`, `skeleton`, `skull`
Fun/Meme	`bong`, `flaming-sheep`, `three-eyes`, `mutilated`, `surgery`, `supermilker`
Combos	`dragon-and-cow`, `mech-and-cow`, `luke-koala`, `vader-koala`, `elephant-in-snake`

# List all available templates
critter list

# Get details about a specific template
critter info cow

# Show a creature with no text bubble
critter show dragon

# List variants for a template
critter variants cow     # Shows: default, dead, borg, greedy, etc.

Animation in Your Terminal

Templates automatically animate when displayed in a TTY:

# Animated creatures (animation plays in real terminal)
critter -t dragon "Fire breath!"
critter -t vader "Heavy breathing..."
critter -t cow "Tail swishing"

# Control animation speed
critter -t dragon --speed 2.0 "Fast dragon!"
critter -t dragon --speed 0.5 "Slow dragon..."

# Disable animation (for piping output)
critter --no-animate -t dragon "Static dragon" | lolcat

Built-in Fortune

No need to pipe from fortune — critter has its own wisdom built in:

# Random fortune from all categories
critter fortune

# Programming quotes
critter fortune --category programming

# Philosophical wisdom
critter fortune --category wisdom

# Daily affirmations
critter fortune --category affirmation

# With a different template
critter fortune -c programming -t ferris

Bubble Styles

# Different bubble styles
critter --bubble round "Round bubble"
critter --bubble square "Square bubble"
critter --bubble thick "Thick bubble"
critter --bubble ascii "ASCII only"
critter --bubble think "Thinking..."
critter --bubble yell "SHOUTING!"
critter --bubble whisper "quietly..."

# Or use the shorthand commands
critter think "Pondering..."
critter yell "HEY!"
critter whisper "secrets"

# No bubble, just the creature
critter --no-bubble -t tux

Rainbow & Gradients

# Rainbow colors (built-in lolcat!)
critter --rainbow "Hello colorful world!"

# Custom gradient
critter --gradient "red,yellow,green" "Traffic light message"

# Rainbow with any command
critter fortune --rainbow
critter --exec "date" --rainbow

Text Styling

# Text effects
critter --bold "Important message"
critter --italic "Emphasized text"
critter --underline "Highlighted"
critter --dim "Subtle note"

# Colors (named, hex, or 256-palette)
critter --fg red "Error message"
critter --fg '#ff5500' --bg black "Custom colors"
critter --fg 196 "Using 256-color palette"

# Color themes
critter --theme cyberpunk "Neon dreams"    # Cyan/Magenta/Yellow
critter --theme forest "Nature vibes"      # Greens/Golds
critter --theme ocean "Cool blues"         # Blue tones
critter --theme sunset "Warm colors"       # Orange/Red

# Combine styles
critter --bold --fg red --bg white "ALERT!"
critter --italic --underline --fg cyan "Styled text"

# See all styling options
critter style-demo

Command Execution

# Speak command output
critter --exec "date"
critter --exec "git log -1 --oneline"
critter --exec "uptime"

# Watch mode: re-run every N seconds
critter --exec "df -h /" --watch 5
critter --exec "kubectl get pods" --watch 10

# Combine with template/variant
critter --exec "curl -s wttr.in?format=3" -t robot

Streaming Mode

# Live-updating output (great for logs!)
tail -f /var/log/syslog | critter --stream
kubectl logs -f deployment/app | critter --stream
journalctl -f | critter --stream -t robot

Animation

# Animated templates play automatically in TTY
critter -t dragon "Roar!"

# Disable animation (useful for piping)
critter --no-animate -t dragon "Roar!" | lolcat

# Adjust animation speed
critter -t dragon --speed 2.0 "Fast dragon!"

Spinners & Progress Bars

# Show a spinner animation (44+ styles available!)
critter spinner dots -m "Loading..." -d 5
critter spinner arc -m "Processing..."
critter spinner shark -d 3

# List all spinner styles
critter spinners
critter spinners --preview   # Live preview of each

# Spinner categories: braille, ascii, blocks, symbols, novelty
critter spinner material     # Material design loading
critter spinner fish         # Fun fish animation
critter spinner binary       # Matrix-style binary

# Progress bars
critter progress -s blocks -w 30 -d 2
critter progress -s smooth -w 30       # Sub-character resolution
critter progress -s ascii -w 25
critter progress -s braille -w 25

# Full animation demo
critter animate-demo

Animation Effects

# Text effects (8 types!)
critter effect typewriter "Hello, World!" -d 5
critter effect rainbow "Colorful text" -d 0   # Infinite loop
critter effect glitch "Corrupted data"
critter effect matrix                          # Full-screen matrix rain
critter effect scramble "Decoding message..."
critter effect neon "Flickering sign"

# Particle systems
critter particles rain -w 80 -H 24
critter particles snow -d 10
critter particles firework
critter particles confetti
critter particles fire
critter particles bubbles

# Animated scenes
critter scene demo -w 60 -H 16        # Gremlin with stars
critter scene celebration -d 15        # Party with confetti
critter scene matrix                   # Full-screen matrix

# List all available effects
critter effects

Color Modes

# Force color mode
critter --color truecolor "Full RGB!"
critter --color color256 "256 colors"
critter --color color16 "Basic colors"
critter --color none "No colors"

Other Commands

# Show template info
critter info cow

# Validate custom templates
critter validate ~/.config/critter/templates/my-creature.toml

# Initialize config directory with example templates
critter init

Creating Templates

Templates are TOML files that define creatures and their properties.

Simple Template

[meta]
name = "my-creature"
version = "1.0.0"
description = "My custom creature"
tags = ["custom", "cute"]

[creature]
bubble_anchor = [0, 4]
bubble_direction = "left"

[[creature.frames]]
art = [
    "  \\",
    "   \\  (o_o)",
    "      <| |>",
    "      /| |\\",
]

[bubble]
padding = 1

Template with Variants

[meta]
name = "cat"
version = "1.0.0"

[creature]
bubble_anchor = [0, 4]

[[creature.frames]]
art = [
    "  \\",
    "   \\ /\\_/\\",
    "    ( o.o )",
]

[variants.sleepy]
[[variants.sleepy.frames]]
art = [
    "  \\",
    "   \\ /\\_/\\",
    "    ( -.- ) zzZ",
]

Template with Colors

[[creature.frames]]
art = [
    "  *  ",
    " *** ",
    "*****",
]

[creature.frames.colors]
"0:2" = { r = 255, g = 215, b = 0 }  # Gold star tip
"1:1" = { r = 255, g = 200, b = 0 }
"1:2" = { r = 255, g = 200, b = 0 }
"1:3" = { r = 255, g = 200, b = 0 }

Template Directory Structure

~/.config/critter/
├── config.toml           # Global configuration
└── templates/
    ├── my-creature.toml  # Simple template
    └── complex-creature/ # Multi-file template
        ├── template.toml
        └── frames/
            ├── 001.txt
            └── 002.txt

Configuration

Create ~/.config/critter/config.toml:

[general]
default_template = "cow"
# color_mode = "auto"  # auto, truecolor, 256, 16, none
# force_unicode = true

[animation]
fps = 10
# disable = false

[theme]
# bubble_color = "cyan"
# text_color = "white"

[paths]
template_dirs = [
    "~/.config/critter/templates",
    "~/.local/share/critter/templates",
]

Builtin Templates

59 animated creatures — all with multi-frame animations and mood variants!

Original Critter Mascots

Template	Description	Variants
`gremlin`	The official critter mascot!	happy, mischief, sleepy, angry, dead, hacker, love
`ferris`	Ferris the Rustacean crab	happy, unsafe, thinking, compiling, panicking
`blinky`	Pac-Man's red ghost	chase, scared, eaten

Classic Cowsay Creatures (Animated!)

Template	Description	Variants
`cow`	The classic cow	dead, borg, greedy, paranoid, stoned, tired, wired, young, moo
`tux`	Tux the Linux penguin	happy, angry, sudo
`dragon`	Fire-breathing dragon	angry, sleepy
`stegosaurus`	Stomping dinosaur	roar
`elephant`	Trumpeting elephant	happy, spray
`sheep`	Fluffy baa-ing sheep	sleepy, fluffy
`moose`	Majestic moose	majestic, canadian
`turtle`	Slow and steady turtle	hiding, sleepy
`koala`	Cute koala	—
`llama`	Spitting llama	—
`alpaca`	Fluffy alpaca	—
`fox`	Clever fox	—

Birds

Template	Description	Variants
`owl`	Wise hooting owl	wise, sleepy, alert
`penguin`	Waddling penguin	cold, fish
`parrot`	Colorful talking parrot	pirate, mimic, dancing
`turkey`	Gobbling turkey	—

Cats & Small Animals

Template	Description	Variants
`cat`	Simple cat	sleepy, happy
`kitty`	Cute kitty	sleepy, surprised, playful, happy
`bunny`	Cute bunny	sleepy, happy
`hellokitty`	Hello Kitty style	—
`meow`	Another cat	—

Spooky & Fantasy

Template	Description	Variants
`ghost`	Spooky ghost	scared, angry
`skeleton`	Rattling skeleton	dancing, scary, fallen
`daemon`	BSD daemon	angry, happy
`ghostbusters`	Who you gonna call?	—
`eyes`	Mysterious eyes	—

Sci-Fi & Pop Culture

Template	Description	Variants
`vader`	Darth Vader with breathing	father, saber, darkside
`sus`	Among Us crewmate	impostor, emergency, venting
`robot`	Friendly robot	happy, angry
`kosh`	Kosh from Babylon 5	—

Classic Cowsay Characters

Template	Description
`beavis`	Beavis from Beavis & Butt-Head
`stimpy`	Stimpy from Ren & Stimpy
`ren`	Ren from Ren & Stimpy
`bud-frogs`	Budweiser frogs
`blowfish`	Puffer fish

Novelty & Memes

Template	Description
`bong`	Water pipe
`cheese`	Block of cheese
`cupcake`	Sweet cupcake
`flaming-sheep`	Sheep on fire
`milk`	Carton of milk
`small`	Tiny creature

Composite & Special

Template	Description
`dragon-and-cow`	Dragon with cow
`elephant-in-snake`	Le Petit Prince reference
`mech-and-cow`	Mech suit with cow
`kiss`	KISS band
`luke-koala`	Luke Skywalker koala
`vader-koala`	Vader koala
`moofasa`	Mufasa as a cow
`mutilated`	Mutilated cow
`surgery`	Surgery scene
`supermilker`	Super milking cow
`udder`	Just an udder
`cower`	Cowering cow
`head-in`	Head in sand
`three-eyes`	Three-eyed creature
`www`	World Wide Web cow

License

MIT

Credits

Inspired by the classic cowsay by Tony Monroe and fortune from BSD games.

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.github/workflows		.github/workflows
crates		crates
docs		docs
fortunes		fortunes
src		src
templates		templates
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
demo.gif		demo.gif
demo.tape		demo.tape

Folders and files

Latest commit

History

Repository files navigation

Ruinsay

Features

Ecosystem

Use from Python

Use from Rust

Use in Browser (WASM)

Use in Neovim (Lua)

Installation

Prebuilt Binaries

From Source

Shell Completions

Usage

Basic Usage

Templates

Cowsay Creatures (Animated!)

Animation in Your Terminal

Built-in Fortune

Bubble Styles

Rainbow & Gradients

Text Styling

Command Execution

Streaming Mode

Animation

Spinners & Progress Bars

Animation Effects

Color Modes

Other Commands

Creating Templates

Simple Template

Template with Variants

Template with Colors

Template Directory Structure

Configuration

Builtin Templates

Original Critter Mascots

Classic Cowsay Creatures (Animated!)

Birds

Cats & Small Animals

Spooky & Fantasy

Sci-Fi & Pop Culture

Classic Cowsay Characters

Novelty & Memes

Composite & Special

License

Credits

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages