Skip to content

MagikIO/familiar-says

BranchesTags

Repository files navigation

familiar-says

Test Suite Go Report Card

A modern, feature-rich replacement for cowsay built in Go. Create personality-themed speech bubbles with rich styling, animations, and visual effects.

Features

  • 🎨 Rich Styling - Beautiful terminal output using Charm Lipgloss
  • 😊 Mood-Based Expressions - Multiple emotional states (happy, sad, angry, surprised, etc.)
  • ⌨️ Typing Animations - Watch your messages appear character by character
  • 🎭 Personality Themes - Default, Rainbow, Cyber, and Retro themes with unique color schemes
  • 🎆 Visual Effects - Confetti, fireworks, sparkles, and rainbow effects
  • 🐮 Custom Characters - Support for traditional .cow character files
  • 💭 Bubble Styles - Both speech and thought bubbles
  • 🎪 Multi-Panel Layouts - Display multiple characters at once (experimental)

Installation

From Source

git clone https://github.com/MagikIO/familiar-says.git
cd familiar-says
go build -o familiar-says .

Using Go Install

go install github.com/MagikIO/familiar-says@latest

Quick Start

Basic usage:

familiar-says "Hello, World!"

With mood and theme:

familiar-says --mood happy --theme rainbow "I'm so happy!"

With animation:

familiar-says --animate "Watch me type..."

With effects:

familiar-says --effect confetti "Celebration time!"

Using a built-in character:

familiar-says --character cat "Meow!"

Usage

familiar-says [message] [flags]

Flags:
  -a, --animate              Enable typing animation
  -c, --character string     Character to use (cat, owl, fox, bunny, penguin, dragon, robot, bat, turtle, default)
  -C, --list-characters      List available characters
  -e, --effect string        Visual effect (none, confetti, fireworks, sparkle, rainbow, rainbow-text) (default "none")
  -E, --list-effects         List available effects
  -M, --list-moods           List available moods
  -T, --list-themes          List available themes
  -m, --mood string          Mood expression (happy, sad, angry, surprised, bored, excited, neutral, sleepy) (default "neutral")
  -p, --multipanel           Enable multi-panel mode (experimental)
  -s, --speed int            Animation speed in milliseconds (default 50)
  -t, --theme string         Theme to use (default, rainbow, cyber, retro) (default "default")
      --think                Use thought bubble instead of speech bubble
  -w, --width int            Width of speech bubble (default 40)
      --outline-color string Color for character outline/body (hex, ANSI, or name)
      --eye-color string     Color for character eyes (hex, ANSI, or name)
      --mouth-color string   Color for character mouth (hex, ANSI, or name)
      --list-colors          List available named colors
  -h, --help                 help for familiar-says

Configuration

familiar-says supports configuration files, profiles, and environment variables to reduce repetitive flag usage.

Config File

Create a config file at ~/.config/familiar-says/config.json:

{
  "default": {
    "character": "cat",
    "theme": "cyber",
    "mood": "happy",
    "width": 50
  }
}

All flags can be configured:

  • character, theme, mood, width, animate, speed, effect, think, multipanel
  • outlineColor, eyeColor, mouthColor

Profiles

Define multiple profiles for different use cases:

{
  "default": {
    "character": "cat",
    "width": 50
  },
  "profiles": {
    "work": {
      "character": "owl",
      "theme": "cyber",
      "mood": "neutral"
    },
    "fun": {
      "character": "dragon",
      "theme": "rainbow",
      "effect": "sparkle",
      "animate": true
    },
    "presentation": {
      "character": "robot",
      "theme": "cyber",
      "width": 80,
      "animate": true,
      "speed": 40
    }
  }
}

Use profiles with the --profile flag:

familiar-says --profile work "Meeting at 3pm"
familiar-says --profile fun "Party time!"

Environment Variables

Override config values using environment variables:

export FAMILIAR_SAYS_CHARACTER="owl"
export FAMILIAR_SAYS_THEME="cyber"
export FAMILIAR_SAYS_MOOD="neutral"

familiar-says "Using env vars!"

All flags have corresponding environment variables with the FAMILIAR_SAYS_ prefix:

  • FAMILIAR_SAYS_CHARACTER, FAMILIAR_SAYS_THEME, FAMILIAR_SAYS_MOOD
  • FAMILIAR_SAYS_WIDTH, FAMILIAR_SAYS_SPEED
  • FAMILIAR_SAYS_ANIMATE, FAMILIAR_SAYS_THINK, FAMILIAR_SAYS_MULTIPANEL (use true/false, 1/0, or yes/no)
  • FAMILIAR_SAYS_EFFECT
  • FAMILIAR_SAYS_OUTLINE_COLOR, FAMILIAR_SAYS_EYE_COLOR, FAMILIAR_SAYS_MOUTH_COLOR
  • FAMILIAR_SAYS_PROFILE

Precedence Order

Configuration sources are applied in this order (highest priority last):

  1. Defaults - Built-in defaults
  2. Config File - Values from ~/.config/familiar-says/config.json
  3. Environment Variables - FAMILIAR_SAYS_* env vars
  4. CLI Flags - Command-line flags (always win)

This allows you to set defaults in your config file, override them per-session with environment variables, and override everything with explicit CLI flags.

Themes

Default

Classic terminal colors with standard ASCII expressions

  • Eyes: oo, ^^, TT, etc.

Rainbow

Colorful Unicode expressions with vibrant colors

  • Eyes: ◕‿◕, •́︵•̀, ಠ_ಠ, etc.

Cyber

Green matrix-style with boxed expressions

  • Eyes: [^_^], [;_;], [>_<], etc.

Retro

Orange/amber colors with classic emoticons

  • Eyes: :D, :(, >:(, etc.

Moods

  • neutral - Default calm expression
  • happy - Joyful expression
  • sad - Sorrowful expression
  • angry - Upset expression
  • surprised - Shocked expression
  • bored - Uninterested expression
  • excited - Enthusiastic expression
  • sleepy - Tired expression

Each theme has unique eye and tongue expressions for each mood!

Effects

Confetti

Adds colorful confetti characters around the output

familiar-says --effect confetti "Party time!"

Fireworks

Creates firework-like star bursts

familiar-says --effect fireworks "Boom!"

Sparkle

Adds sparkle emojis around the output

familiar-says --effect sparkle "Shiny!"

Rainbow

Colors each character with rainbow colors

familiar-says --effect rainbow "Colorful!"

Rainbow Text

Applies rainbow colors only to the message text (not the character)

familiar-says --effect rainbow-text "Colorful message!"

Custom Characters

familiar-says includes several built-in character familiars:

  • default - Classic cow
  • cat - Cute cat
  • bunny - Adorable bunny
  • dragon - Majestic dragon
  • owl - Wise owl
  • fox - Clever fox
  • penguin - Waddle penguin
  • robot - Mechanical robot
  • bat - Night bat
  • turtle - Slow turtle

Characters are defined using JSON files with support for customizable colors and anchor positions. Example format:

{
  "name": "cat",
  "description": "A cute cat familiar",
  "art": [
    "  /\\_/\\  ",
    " ( @@ ) ",
    " =( Y )=",
    "   ^ ^  "
  ],
  "anchor": {"x": 4, "y": 0},
  "eyes": {
    "line": 1,
    "col": 3,
    "width": 2,
    "placeholder": "@@"
  },
  "mouth": {
    "line": 2,
    "col": 4,
    "width": 1,
    "placeholder": "Y"
  },
  "colors": {
    "eyes": "#7CFC00",
    "mouth": "#FF69B4"
  }
}

Character Color Customization

You can customize character colors using the color flags:

# Custom colored cat
familiar-says --character cat --eye-color "#00FF00" --mouth-color pink "Custom colors!"

# Full color customization
familiar-says --character dragon --outline-color fire --eye-color gold --mouth-color red "Fiery dragon!"

# See all available named colors
familiar-says --list-colors

Supported color formats:

  • Hex codes: #FF6B6B, #F6B, FF6B6B
  • ANSI 256: 196, 82, 46
  • Named colors: red, blue, pink, fire, ocean, sunset, etc.

Examples

Combine features:

# Happy cat with rainbow effect
familiar-says --character cat --mood happy --effect rainbow "I love rainbows!"

# Animated angry cyber-themed message
familiar-says --mood angry --theme cyber --animate --speed 30 "System breach detected!"

# Thought bubble with sparkles
familiar-says --think --effect sparkle "What should I think about?"

# Custom width for long messages
familiar-says --width 60 "This is a much longer message that needs more space to display properly without wrapping too much."

# Custom colored owl
familiar-says --character owl --eye-color gold --mood wise "Hoot hoot!"

Piping input:

echo "Hello from stdin!" | familiar-says

fortune | familiar-says --mood happy --theme rainbow

Architecture

The project is organized into several packages:

  • internal/bubble - Speech bubble generation with word wrapping
  • internal/personality - Theme and mood system
  • internal/animation - Terminal animations using Bubble Tea
  • internal/effects - Visual effects engine
  • internal/character - Character rendering engine (loads JSON character files)
  • internal/canvas - Low-level character rendering with color support and composition
  • internal/config - Configuration file, profile, and environment variable management
  • internal/errors - Custom error types with consistent formatting
  • cmd - CLI application using Cobra
  • characters/ - Built-in character definitions in JSON format

Error Handling

The application features comprehensive error handling with:

  • Custom error types for better error context (CharacterLoadError, ColorParseError, ValidationError)
  • Wrapped errors using fmt.Errorf with %w for full error chains
  • Input validation at entry points with user-friendly messages
  • Graceful degradation for terminal width detection failures
  • Clear error messages showing exactly what went wrong and where

Dependencies

Contributing

Contributions are welcome! Feel free to:

  • Add new themes
  • Create new character files
  • Implement new effects
  • Improve animations
  • Fix bugs

License

MIT License - see LICENSE file for details

Credits

Inspired by the classic cowsay by Tony Monroe. Built with ❤️ using Charm libraries.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages