Paint

A design toolkit for managing color palettes, gradients, swatches, and design assets. Each command category maintains its own timestamped log file, so you can organize design entries by purpose — palettes, previews, color conversions, harmonies, contrasts, gradients, swatches, and more. Includes built-in statistics, multi-format export, full-text search, and activity history.

All operations are logged with timestamps and stored locally in flat files for easy inspection and portability.

Commands

Command	Description
`paint palette <text>`	Record a palette entry (or show recent palettes with no args)
`paint preview <text>`	Log a design preview note
`paint generate <text>`	Record a generated design asset or color scheme
`paint convert <text>`	Log a color space conversion (e.g., HEX to RGB)
`paint harmonize <text>`	Record a color harmony analysis
`paint contrast <text>`	Log a contrast check or accessibility evaluation
`paint export <text>`	Record an export operation or design asset output
`paint random <text>`	Log a randomly generated color or pattern
`paint browse <text>`	Record a browsed design reference or inspiration
`paint mix <text>`	Log a color mixing operation
`paint gradient <text>`	Record a gradient definition or transition
`paint swatch <text>`	Log a swatch entry or named color sample
`paint stats`	Show summary statistics across all categories
`paint search <term>`	Full-text search across all log files
`paint recent`	Show the 20 most recent activity entries
`paint status`	Health check — version, data dir, entry counts, disk usage
`paint help`	Show the built-in help message
`paint version`	Print the current version

How Entry Commands Work

Every entry command (palette, preview, generate, convert, harmonize, contrast, export, random, browse, mix, gradient, swatch) follows the same pattern:

With arguments: Appends a timestamped entry (YYYY-MM-DD HH:MM|<text>) to the corresponding .log file and shows the new total count
Without arguments: Shows the 20 most recent entries from that category's log file

Data Storage

All data is stored in ~/.local/share/paint/ by default.

Files created in the data directory:

palette.log, preview.log, generate.log, convert.log, harmonize.log, contrast.log, export.log, random.log, browse.log, mix.log, gradient.log, swatch.log — One log file per command category, each containing timestamped entries in YYYY-MM-DD HH:MM|<text> format
history.log — Audit trail of every command executed with timestamps
export.json / export.csv / export.txt — Generated by the stats/export functions

Export Formats (via internal `_export` function)

json — Array of objects with type, time, and value fields
csv — Header row (type,time,value) followed by data rows
txt — Human-readable sections grouped by category

Requirements

bash 4.0 or later (uses set -euo pipefail, local variables)
grep — used by the search command for case-insensitive matching
Standard POSIX utilities — date, cat, echo, mkdir, wc, du, head, tail, basename
No external API keys or network access required
No Python or Node.js dependencies

When to Use

Building a color palette library — Use palette to log color combinations as you discover or create them, then search to find specific palettes later
Tracking design iterations — Use preview and generate to record design experiments, then recent to review your latest work
Color space documentation — Use convert to log color conversions (HEX → RGB → HSL) for reference in design systems or style guides
Accessibility audits — Use contrast to document contrast ratio checks between foreground and background colors for WCAG compliance
Gradient and swatch management — Use gradient and swatch to maintain a library of reusable color transitions and named color samples

Examples

# Record a new palette
paint palette "Sunset: #FF6B35, #F7931E, #FCB040, #FDD835"
#=> [Paint] palette: Sunset: #FF6B35, #F7931E, #FCB040, #FDD835
#=> Saved. Total palette entries: 1

# Log a color conversion
paint convert "Brand blue: #2196F3 → rgb(33,150,243) → hsl(207,90%,54%)"
#=> [Paint] convert: Brand blue: #2196F3 → rgb(33,150,243) → hsl(207,90%,54%)
#=> Saved. Total convert entries: 1

# Record a gradient
paint gradient "Hero section: linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
#=> [Paint] gradient: Hero section: linear-gradient(135deg, #667eea 0%, #764ba2 100%)
#=> Saved. Total gradient entries: 1

# Check a contrast ratio
paint contrast "White #FFF on brand blue #2196F3: ratio 3.2:1 — fails AA for body text"
#=> [Paint] contrast: White #FFF on brand blue #2196F3: ratio 3.2:1 — fails AA for body text
#=> Saved. Total contrast entries: 1

# View statistics across all categories
paint stats
#=> === Paint Stats ===
#=>   palette: 1 entries
#=>   convert: 1 entries
#=>   gradient: 1 entries
#=>   contrast: 1 entries
#=>   ---
#=>   Total: 4 entries
#=>   Data size: 4.0K

# Search across all logs
paint search "blue"
#=> Searching for: blue
#=>   --- convert ---
#=>     2025-03-18 14:30|Brand blue: #2196F3 → rgb(33,150,243)

Configuration

The data directory is hardcoded to ~/.local/share/paint/. To use a custom location, modify the DATA_DIR variable in the script.

How It Works

On every invocation, the tool ensures the data directory exists (mkdir -p)
The first argument selects the command via a case dispatch
Entry commands append a pipe-delimited line (timestamp|text) to their category-specific log file
Every command also appends to history.log for auditing
stats iterates over all .log files to produce aggregate counts
search uses grep -i across all log files for case-insensitive matching
All output goes to stdout for easy piping and redirection