https://github.com/vnykmshr/gowsay
Modern cowsay in Go: CLI tool, REST API, and web UI in a single binary with 52 cows and 8 moods. Minimal dependencies, stdlib-first.
https://github.com/vnykmshr/gowsay
ascii-art cli-tool cowsay docker golang rest-api single-binary slack-integration web-ui
Last synced: about 1 month ago
JSON representation
Modern cowsay in Go: CLI tool, REST API, and web UI in a single binary with 52 cows and 8 moods. Minimal dependencies, stdlib-first.
- Host: GitHub
- URL: https://github.com/vnykmshr/gowsay
- Owner: vnykmshr
- License: mit
- Created: 2024-11-01T17:04:55.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-24T23:57:23.000Z (4 months ago)
- Last Synced: 2025-11-28T10:27:55.223Z (4 months ago)
- Topics: ascii-art, cli-tool, cowsay, docker, golang, rest-api, single-binary, slack-integration, web-ui
- Language: Go
- Homepage: https://gowsay.vnykmshr.com
- Size: 144 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
## gowsay
Implementation of cowsay in Go
**Single binary, multiple modes:**
- Command-line tool (like original cowsay)
- HTTP API server for Slack integration
- Web UI with embedded assets
- 51 different cows
- 8 moods (borg, dead, greedy, paranoid, stoned, tired, wired, young)
**Status:** gowsay 2.0 - CLI tool, Web UI, JSON API
## Usage
### CLI Tool
```bash
# Basic usage
gowsay "Hello World"
# Use a different cow
gowsay -c dragon "Fire!"
# Make the cow think instead of speak
gowsay -t "Hmm..."
# Random cow and mood
gowsay -r "Surprise!"
# Use mood
gowsay -c tux -m dead "System crashed"
# From pipe
echo "Hello from pipe" | gowsay
# List available cows and moods
gowsay -l
# Help
gowsay --help
```
### Web Interface
Start the server and open http://localhost:9000 in your browser:
```bash
./bin/gowsay serve
# or with custom port
PORT=8080 ./bin/gowsay serve
```
**Features:**
- Modern, polished UI with dark mode
- Choose from 51 different cows
- Apply moods (borg, dead, greedy, etc.)
- Random button for surprise cows
- Copy output to clipboard
- Mobile responsive
### HTTP API
**Endpoints:**
```bash
# Generate cowsay (query params)
curl 'http://localhost:9000/api/moo?text=Hello&cow=dragon&action=say'
# Generate cowsay (JSON)
curl -X POST http://localhost:9000/api/moo \
-H 'Content-Type: application/json' \
-d '{"text":"Hello","cow":"dragon","mood":"wired"}'
# List all cows
curl http://localhost:9000/api/cows
# List all moods
curl http://localhost:9000/api/moods
# Health check
curl http://localhost:9000/health
```
**API Parameters:**
- `text` - Message to display (required)
- `cow` - Cow name (default: "default", or "random")
- `mood` - Mood name (optional, or "random")
- `action` - "say" or "think" (default: "say")
- `columns` - Text width for wrapping (default: 40)
**Error Responses:**
```json
{"error": "text is required"}
{"error": "cow 'invalid' not found"}
{"error": "mood 'invalid' not found"}
```
### Slack Command
Deployed at https://gowsay.vnykmshr.com/say
```
/moo [think|surprise] [cow] [mood] message
```
### Cows
```
`apt`, `beavis.zen`, `bong`, `bud-frogs`, `bunny`, `calvin`, `cheese`, `cock`, `cower`,
`daemon`, `default`, `dragon`, `dragon-and-cow`, `duck`, `elephant`, `elephant-in-snake`,
`eyes`, `flaming-sheep`, `ghostbusters`, `gnu`, `head-in`, `hellokitty`, `kiss`, `kitty`,
`koala`, `kosh`, `luke-koala`, `mech-and-cow`, `meow`, `milk`, `moofasa`, `moose`,
`mutilated`, `pony`, `pony-smaller`, `ren`, `sheep`, `skeleton`, `snowman`,
`sodomized-sheep`, `stegosaurus`, `stimpy`, `suse`, `three-eyes`, `turkey`, `turtle`,
`tux`, `unipony`, `unipony-smaller`, `vader`, `vader-koala`, `www`
```
### Moods
```
`borg`, `dead`, `greedy`, `paranoid`, `stoned`, `tired`, `wired`, `young`
```
## Configuration
Configuration via environment variables:
- `PORT` - Server port (default: `9000`)
- `GOWSAY_TOKEN` - Authentication token (default: `devel`, allows any request - set in production)
- `GOWSAY_COLUMNS` - Text column width (default: `40`)
## Development
### Build
```bash
make build
# or
go build -ldflags "-X 'main.version=`git log -1 --pretty=format:"%h"`'" -v
```
### Run CLI
```bash
./bin/gowsay "Hello World"
```
### Run Server
```bash
make run/server
# or
./bin/gowsay serve
# or with custom port
PORT=8080 ./bin/gowsay serve
```
### Test
```bash
make test
```
### Cross-compile
Linux:
```bash
GOOS=linux GOARCH=amd64 go build -o bin/gowsay-linux
```
Raspberry Pi:
```bash
GOOS=linux GOARCH=arm GOARM=5 go build -o bin/gowsay-pi
```
### Docker
Build and run with Docker:
```bash
# Build image
docker build -t gowsay .
# Run container
docker run -p 9000:9000 gowsay
# Or use docker compose
docker compose up
```
Docker image details:
- Multi-stage build using Go 1.23
- Final image uses scratch base (~11MB including embedded web assets)
- Default command runs server mode
- Can override for CLI: `docker run gowsay --help`
### Slack Integration
Example request:
```bash
curl -X POST 'https://gowsay.vnykmshr.com/say' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=xxx' \
--data-urlencode 'text=Hello World'
```
## Documentation
- [Architecture Overview](docs/ARCHITECTURE.md) - System design and package structure
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Technical Blog](docs/TECHNICAL_BLOG.md) - Deep dive into design decisions
- [Security Policy](SECURITY.md) - Reporting vulnerabilities
## License
MIT License - see [LICENSE](LICENSE) for details