Usage

Every Cowser command, end to end.

Table of Contents

• Installation
• Command line
• Configuration
• Art packs
• Binaries

Installation

pip install cowser               # CLI + library
pip install "cowser[color]"      # colorama for legacy Windows consoles

Requires Python 3.8+.

Command line

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

Options

Option	Description
-c, --cow NAME_OR_INDEX	Choose an animal by name, prefix, or index.
-e, --eyes CHARS	Replace the {eyes} token in the art.
--mode MODE	Preset style: borg, dead, greedy, paranoid, stoned, drunk, wired, youthful.
--tongue CHARS	Replace the {tongue} token in the art.
--think	Use a thought bubble instead of a speech bubble.
-W, --wrap WIDTH	Word-wrap the message to WIDTH columns.
-n, --no-wrap	Disable word wrapping.
--rainbow	Colorize output line by line in rainbow order.
--bold	Make the output bold.
--fortune	Show a random fortune instead of a message.
--and NAME_OR_INDEX	Render a second animal next to the first.
--interactive	Start an interactive REPL session.
--cow-dir DIR	Load extra animals from a directory.
--seed INT	Seed random selection for reproducible output.
-m, --message TEXT	Show a custom message instead of a greeting.
-l, --list	List all available animals.
--search TEXT	List animals matching name, category, or tag.
--color COLOR	Output color (default: cyan).
--no-color	Disable colored output.
-V, --version	Show version.

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"
mode = "dead"
wrap = 40
cow_dir = "~/my-cows"
# seed = 42

Art packs

Add your own animals without editing the package. Point Cowser at a directory of art files:

cowser --cow-dir ./my-cows "hello from my pack"

Packs are also discovered automatically from the COWSER_COWS environment variable (path-separator separated), the cow_dir config key, and ~/.config/neostore/cowser/cows/. Supported files:

• *.cow — classic cowsay cowfiles. $eyes/$tongue/$thoughts placeholders are mapped to tokens automatically.
• *.txt / *.art — the whole file is used as the art (may contain {eyes} / {tongue|} tokens).

Each file becomes a cow named after its file stem. Duplicate names are skipped.

Binaries

Standalone binaries (no Python needed):

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

The binary lands in dist/ (cowser.exe on Windows).

See also: installation.md, cli.md, configuration.md, and api.md.

---

← Back to README