cli-web-unsplash

Search, explore, and download Unsplash photos (read-only, no auth). Install: pip install cli-web-unsplash

Commands

Examples

# Search with filters (returns total, total_pages, results[] with id, likes, author, url)
cli-web-unsplash photos search "sunset" --orientation landscape --color orange --per-page 10 --json

# Photo details (EXIF, location, tags)
cli-web-unsplash photos get SyfvrXRy28Y --json

# Random nature photos
cli-web-unsplash photos random --query "nature" --count 3 --json

# Search then download the top hit
ID=$(cli-web-unsplash photos search "sunset beach" --per-page 1 --json | jq -r '.results[0].id')
cli-web-unsplash photos download "$ID" --size regular -o sunset.jpg

# A photographer's most popular photos
cli-web-unsplash users photos unsplash --order-by popular --per-page 5 --json

JSON output

Every command accepts --json and returns the data directly (search: {"total", "total_pages", "results": [...]}; download: {"photo_id", "size", "file", "bytes"}). Errors return {"error": true, "code": "...", "message": "..."}.

Utilities

cli-web-unsplash doctor [--json] self-diagnoses the local setup (install, auth, dependencies). cli-web-unsplash mcp-serve serves the commands as MCP tools over stdio.

Agent tips

• Some results have premium: true (Unsplash+ only) — skip those when the user wants freely usable images.
• Use urls.regular for web-quality embeds and urls.raw for full resolution.