unsplash-cli

cli-web-unsplash

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

Commands

| Command | Purpose | Key options | |---------|---------|-------------| | photos search QUERY | Search photos | --orientation landscape\|portrait\|squarish, --color, --order-by relevant\|latest, --page, --per-page (max 30) | | photos get PHOTO_ID | Full details: EXIF, location, tags, URLs | ID or slug | | photos random | Random photo(s) | --query, --orientation, --count N (max 30) | | photos download PHOTO_ID | Download to disk | --size raw\|full\|regular\|small\|thumb, -o/--output PATH | | photos stats PHOTO_ID | Views and downloads | | | topics list / topics get SLUG / topics photos SLUG | Browse curated topics | --page, --per-page, --order-by | | collections search QUERY / collections get ID / collections photos ID | Browse collections | --page, --per-page | | users search QUERY / users get USERNAME / users photos USERNAME / users collections USERNAME | Photographer profiles and portfolios | --page, --per-page, --order-by (photos: latest\|oldest\|popular\|views\|downloads) |

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.