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, html, tunnel
--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