pokesay

README

pokesay

Print pokemon in the CLI! An adaptation of the classic 'cowsay'

Pokesay is...

• 🏃 a single binary with zero dependencies that can run on any popular OS and architecture.
• ⚙️ flexible, offering many options to select and view Pokemon
• 🚀 the fastest to run compared to similar projects
• 🕶️ modern, supporting unicode borders, japanese names, colourful ANSI text & shell completion

Installation

• Via homebrew (MacOS/Linux/Windows)

  brew install tmck-code/tap/pokesay
  

• Via the AUR (Arch Linux)

  yay -S pokesay-bin
  

For installation without a package manager, see the options below.

Other installation options

Install a release package

This option is supported for Debian and Arch Linux based systems.

1. Navigate to the Releases page.
2. Download the appropriate package for your system
   • .deb for Debian/Ubuntu based systems
   • .pkg.tar.zst for Arch Linux based systems
3. Install the package
   • For .deb files, use sudo dpkg -i pokesay_<version>_linux_amd64.deb
   • For .pkg.tar.zst files, use sudo pacman -U pokesay-<version>-1-x86_64.pkg.tar.zst

Download a pre-built binary

(These commands can also be used to update your existing pokesay)

OS/arch	command
OSX / darwin	bash -c "$(curl https://raw.githubusercontent.com/tmck-code/pokesay/master/build/scripts/install.sh)" \ bash darwin amd64
OSX / darwin (M1)	bash -c "$(curl https://raw.githubusercontent.com/tmck-code/pokesay/master/build/scripts/install.sh)" \ bash darwin arm64
Linux / x64	bash -c "$(curl https://raw.githubusercontent.com/tmck-code/pokesay/master/build/scripts/install.sh)" \ bash linux amd64
Android / arm64 (termux)	bash -c "$(curl https://raw.githubusercontent.com/tmck-code/pokesay/master/build/scripts/install.sh)" \ bash android arm64
Windows / x64 (.exe)	bash -c "$(curl https://raw.githubusercontent.com/tmck-code/pokesay/master/build/scripts/install.sh)" \ bash windows amd64

---

Usage

Just pipe some text! e.g.

echo yolo | pokesay

Note: The pokesay tool is intended to only be used with piped text input from STDIN, entering text by typing (or other methods) might not work as expected!

Examples

Default output	Set bubble width -w	Unicode borders -u
Info border -b	Choose by name -n	No category info -C
Show Japanese name -j	Show ID -I	Small size -c small
Medium size -c medium	Big size -c big	Shiny -c shiny
Size and name -c small -n ...	Size and name -c big -n ...
Select by ID -i	Flip -F	Figlet + lolcat

To see it every time you open a terminal, add it to your .bashrc file!
(This requires that you have fortune installed)

echo 'fortune | pokesay' >> $HOME/.bashrc

Full Usage

Run pokesay with -h or --help to see the full usage

Usage: pokesay [-bBCfFhIjLsuvW] [-c value] [-i value] [-l value] [-n value] [-t value] [-w value] [parameters ...]
 -b, --info-border  draw a border around the info box
 -B, --no-bubble    do not draw the speech bubble
 -c, --category=value
                    choose a pokemon from a specific category
 -C, --no-category-info
                    do not print pokemon category information in the info box
 -f, --fastest      run with the fastest possible configuration (--nowrap &
                    --notabspaces)
 -F, --flip         flip the pokemon horizontally (face right instead of left)
 -h, --help         display this help message
 -i, --id=value     choose a pokemon from a specific ID (see `pokesay -l` for
                    IDs)
 -I, --id-info      print the pokemon ID in the info box
 -j, --japanese-name
                    print the japanese name in the info box
 -L, --list-categories
                    list all available categories
 -l, --list-names[=value]
                    list all available names
 -n, --name=value   choose a pokemon from a specific name
 -s, --no-tab-spaces
                    do not replace tab characters (fastest)
 -t, --tab-width=value
                    replace any tab characters with N spaces [4]
 -u, --unicode-borders
                    use unicode characters to draw the border around the speech
                    box (and info box if --info-border is enabled)
 -v, --verbose      print verbose output
 -W, --no-wrap      disable text wrapping (fastest)
 -w, --width=value  the max speech bubble width [80]

---

How it works

This project extends on the original fortune | cowsay, a simple command combo that can be added to your .bashrc to give you a random message spoken by a cow every time you open a new shell.

 ☯ ~ fortune | cowsay
 ______________________________________
/ Hollywood is where if you don't have \
| happiness you send out for it.       |
|                                      |
\ -- Rex Reed                          /
 --------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

As a personal project, this has been lovingly over-engineered with a focus on the lowest latency possible, so that it doesn't slow down your terminal experience.

1. These pokemon sprites used here are sourced from the awesome repo msikma/pokesprite

   

2. All of these sprites are converted into a form that can be rendered in a terminal (unicode characters and colour control sequences) by the img2xterm tool, found at rossy/img2xterm

3. Use some go tools (encoding/gob and go:embed) to generate a go source code file that encodes all of the converted unicode sprites as gzipped text and some search-optimised data structures.

4. Finally, this is built with the main CLI logic in pokesay.go into an single executable that can be easily popped into a directory in the user's $PATH

If all you are after is installing the program to use, then there are no dependencies required! Navigate to the Releases and download the latest binary.

Similar projects

There are many other projects that bring pokemon to the terminal! Check them out via the links.

Inspired by the pokeshell project, I've included a comparison table

project	language	speed	jp	size	name	category	flip	id	tab completion
tmck-code/pokesay	go	1.7ms	✅	✅	✅	✅	✅	✅	✅
yannjor/krabby	rust	5.2ms	✅	✅	✅	✅	❌	✅	❌
Altair-39/kingler	rust	39.2ms	✅	✅	✅	✅	❌	✅	✅
xiota/pokemon-colorscripts	bash	26.7ms	❌	✅	✅	✅	❌	❌	❌
rubiin/pokego	go	2.0ms	❌	❌	✅	❌	❌	❌	❌
talwat/pokeget-rs	rust	1.5ms	❌	✅	✅	✅	❌	✅	❌
possatti/pokemonsay	cowsay (perl)	26.3ms	❌	❌	✅	❌	❌	✅	❌
HRKings/pokemonsay-newgenerations	cowsay (perl)	26.9ms	❌	✅	✅	✅	❌	✅	❌
dfrankland/pokemonsay	nodejs	180.2ms	❌	✅	✅	❌	❌	✅	❌

---

TODO

• In progress
• Short-term
  • create "vertical" friendly display mode, place the Pokemon standing beside the text box, on the left or right
  • non-say mode (only print the pokemon, no speech bubble)
• Longer-term
  • make the process async.
    • (Currently the searching/pokemon fetching is done before any printing begins. There's an opportunity to start printing the speech bubble while also fetching the pokemon to print below it)
    • implement native lolcat/rainbow HR/colour
• In Beta
  • optionally print ID assigned to each pokemon, support deterministic selection via the same ID
• Completed
  • requesting mew returns mewtwo also
  • shell completion scripts (bash, zsh, fish)
  • add option to flip Pokemon to face right or left, remove all "right" facing cowfiles
  • create Debian package
  • create Arch package
  • support long and short cli args (e.g. --name/-n)
  • Make the category struct faster to load - currently takes up to 80% of the execution time
  • Store metadata and names in a more storage-efficient manner
  • Import japanese names from data/pokemon.json
  • Fix bad whitespace stripping when building assets
  • List all names
  • Make data structure to hold categories, names and pokemon
  • Increase speed
  • Improve categories to be more specific than shiny/regular
  • Filter by both name and category

Other docs

• Building binaries
• Developing/Deploying