Cowser

A fun, cross-platform command-line tool that greets you with ASCII art animals. Inspired by cowsay, written in Python.

Features

• 35+ animals across categories: cows, cats, dogs, birds, sea life, robots, mythical creatures and more
• Greet users with a random animal, or pick one by name/index/prefix
• Custom messages and piping from stdin
• Configurable eyes (--eyes) and tongues (--tongue) on token-based art
• cowsay-style modes (--mode dead, --think, ...)
• Word wrapping for long messages (-W/--wrap, -n/--no-wrap)
• Color themes: rainbow, bold, plus plain colored output
• Fortune mode (--fortune) and two animals at once (--and)
• Interactive REPL (--interactive)
• Colored output (ANSI, works on modern Windows terminals)
• Legacy-console fallback — output is automatically made printable for cp437/cmd.exe and other old codepages
• Windows wrappers (cowser.cmd, cowser.ps1) and single-file binaries built with PyInstaller for Linux/macOS/Windows
• Config file at ~/.config/neostore/cowser/config.toml
• Usable as a library in your own Python code

Installation

Requires Python 3.8+.

pip install cowser

For color support on legacy Windows consoles (cmd.exe pre-Windows 10):

pip install cowser[color]

From source:

git clone https://github.com/rkriad585/Cowser
cd Cowser
pip install .

Usage

cowser Alice                 # greet with a random animal
cowser --cow owl Bob         # pick a specific animal
cowser --message "Hello!"    # custom message
echo "From stdin" | cowser   # pipe a message
cowser --mode dead --cow pig # mood preset (eyes + tongue)
cowser --think --cow owl "Where am I?"
cowser --rainbow --bold --message "Party time!"
cowser --fortune             # random fortune
cowser --cow dog --and cat "Best friends"
cowser --list                # show all animals
cowser --search mythical     # search by name, category, or tag
cowser --interactive         # chat REPL

 _________
/ Hi Bob! \
\__________/
   _____
  / o o \
 (   V   )
  \_____/

Options

Legacy commands

Backwards-compatible with the original script:

python main.py Alice
python main.py help
python main.py list
./cowset Alice

Windows wrappers

On Windows, if python is on your PATH, use the bundled wrappers instead of installing anything extra:

cowser.cmd Alice
cowser.cmd --cow owl --message "Hello"

.\cowser.ps1 Alice
.\cowser.ps1 --think --cow owl "Where am I?"

Single-file binaries

Optional standalone binaries (no Python needed) are built with PyInstaller:

pip install -e ".[binary]"
python scripts/build_binary.py

The binary lands in dist/ (cowser.exe on Windows). CI also builds and attaches Linux/macOS/Windows binaries to every v* git tag.

Legacy consoles

When output cannot be encoded by the current console (e.g. cp437 cmd.exe), Cowser automatically replaces unsupported characters with readable ASCII — smart quotes, dashes, accents, and emoji all get a safe fallback.

Configuration

Defaults are read from ~/.config/neostore/cowser/config.toml. Command-line flags always win. See config.example.toml.

# ~/.config/neostore/cowser/config.toml
color = "green"
cow = "fish"
eyes = "o o"
# seed = 42

Using Cowser as a library

cowser (and its stable surface, cowser.api) exposes a pure, side-effect free API — no I/O — so it is safe to embed in other tools. All public functions are fully type-hinted and documented with examples.

from cowser import COWS, render, render_pair, register_cow, search_cows, Cow

print(render("Hello from my app", cow="owl", eyes="0.0"))
print(render("moo", cow="pig", mode="dead", think=True))
print(render_pair("best friends", "dog", "cat", rainbow=True))

for cow in search_cows(category="mythical"):
    print(cow.name, cow.tags)

register_cow(Cow("my-dragon", "   ~\n  (o.o)", category="mythical"))

The stable public surface is listed in cowser.api.__all__: Cow, COWS, render, render_pair, render_cow, build_speech_bubble, resolve_cow, search_cows, register_cow, substitute_eyes, substitute_tongue, and wrap_text. These names are covered by a backwards-compatibility guarantee.

Adding more animals

Open cowser/cows.py and add a Cow to the COWS list. Art may include an {eyes} token that --eyes replaces, and a {tongue|default} token that --tongue (or --mode) replaces:

Cow("my-cow", r"""   /\
  /  \
 | oo |
  ~~   ~~""", "misc", ("new",)),

Development

pip install -e ".[dev]"
python -m pytest
python -m mypy cowser

Tests and type checks run on Linux, macOS, and Windows via GitHub Actions.

License

MIT © 2026 rkriad585