goAvatar

Generate simple random pixel avatars from the command line or from Go code.

Features

• Symmetric pixel-art avatar generation.
• CLI and importable Go package.
• Configurable grid dimensions, output size, and output file.
• Optional seed for reproducible avatars.
• Local Taskfile commands for run, test, example, and release builds.

Quick Start

Install the CLI:

go install github.com/ethercod3/goAvatar/cmd/goavatar@latest

Generate a 500px avatar with a 5x5 grid:

goavatar -s 500 -d 5 -o avatar.png

For local development:

task run -- -s 500 -d 5 -o avatar.png

CLI

goavatar -s <size> -d <dimensions> [-o <output>] [--seed <seed>]

Short	Long	Required	Description	Default
-d	--dimensions	Yes	Avatar grid dimensions	-
-s	--size	Yes	Output image size in pixels	-
-o	--output	No	Output PNG file path	avatar.png
-	--seed	No	Reproducible random seed; 0 uses a random seed	0

Go Package

package main
import (
"image/png""log""os""github.com/ethercod3/goAvatar/avatar"
)
funcmain() {
options:= avatar.Options{
Dimensions: 5,
FileSizePx: 500,
Seed: 42,
}
img, err:=avatar.New(options)
iferr!=nil {
log.Fatal(err)
}
file, err:=os.Create("avatar.png")
iferr!=nil {
log.Fatal(err)
}
deferfile.Close()
iferr:=png.Encode(file, img); err!=nil {
log.Fatal(err)
}
}

For direct file output:

err:=avatar.Save("avatar.png", avatar.Options{
Dimensions: 5,
FileSizePx: 500,
Seed: 42,
})

Development

This project uses Task for common commands.

Command	Description
task run -- -s 500 -d 5 -o avatar.png	Run the CLI locally
task example	Generate avatar.png with sample options
task test	Run Go tests
task build	Build release binaries into dist/

Equivalent Go commands:

go test ./...
go build ./...
go run ./cmd/goavatar -s 500 -d 5 -o avatar.png

Release Builds

Build cross-platform binaries:

nu scripts/build.nu

The script writes release artifacts to dist/, which is ignored by Git.