Image Well

Search and download images from 12 sources through a single CLI. Four sources work with zero API keys (Openverse, Wikimedia, Met Museum, NASA). Additional sources activate when keys are set.

Quick Start

# Search across all no-key sources
uv run ~/.claude/skills/image-well/scripts/well.py search "ancient Minoan fresco"

# Use a preset for domain-specific searches
uv run ~/.claude/skills/image-well/scripts/well.py search "F-35 fighter jet" --preset military

# Download results with metadata sidecars
uv run ~/.claude/skills/image-well/scripts/well.py search "sunset" --format download --output ./images/

# Check which sources are available
uv run ~/.claude/skills/image-well/scripts/well.py sources

# Visual HTML preview — opens in browser, no context pollution
uv run ~/.claude/skills/image-well/scripts/well.py search "bronze statue" --format html

# Output as JSON for piping
uv run ~/.claude/skills/image-well/scripts/well.py search "cat" --format json

Sources

Tier	Source	Key Required	License
1	Openverse (800M+)	No	CC variants
1	Wikimedia Commons	No	CC variants
1	Met Museum (375k)	No	CC0
1	NASA (140k)	No	Public Domain
2	Pexels	PEXELS_API_KEY	Pexels License
2	Pixabay	PIXABAY_API_KEY	Pixabay License
2	Rijksmuseum (700k)	RIJKSMUSEUM_API_KEY	CC0
2	Unsplash	UNSPLASH_ACCESS_KEY	Unsplash License
3	Smithsonian	No	CC0
3	Europeana (50M+)	EUROPEANA_API_KEY	Mixed
3	Iconify (275k icons)	No	Various
3	Pollinations AI	No	Free Use (AI gen)

Add Tier 2 keys to ~/.config/env/secrets.env for expanded coverage.

Presets

Preset	Sources	Use Case
military	nasa, wikimedia, smithsonian	Defense/military imagery
museum	met, rijksmuseum, smithsonian	Art, antiquities, historical
texture	wikimedia, pollinations	Game dev, 3D materials
stock	pexels, pixabay, unsplash	Editorial photography
all-free	openverse, wikimedia, met, nasa, smithsonian	All no-key sources

Options

--sources NAME [...]    Specific sources to search
--preset NAME           Use a preset group
--limit N               Max results per source (default: 10)
--license LICENSE       Filter: cc0, cc-by, cc-by-sa, any
--format FORMAT         table, json, download, urls
--output DIR            Download directory (default: ./well-images/)
--no-cache              Skip result cache
--timeout N             Per-source timeout in seconds (default: 15)
--quiet                 Suppress progress output

Workflows

Source images for a project

# Search, review in table, then download the good ones
uv run well.py search "Mediterranean landscape" --preset stock --format json > results.json
# Review results.json, then download specific URLs

Build an image corpus

# Download CC0 images for a research project
uv run well.py search "Bronze Age pottery" --preset museum --license cc0 --format download --output ./corpus/

Pipe to image-forge for processing

# Search, download, then resize with image-forge
uv run well.py search "sunset" --format download --output ./raw/
# Then use image-forge skill to process downloaded images

Cache

Results are cached for 24 hours at ~/.cache/image-well/.

uv run well.py cache stats    # Show cache size
uv run well.py cache clear    # Clear all cached results