unsplash-cli - SKILL.md Agent Skill

name: unsplash-cli description: Searches and downloads free Unsplash photos via the cli-web-unsplash command-line tool — keyword search with orientation/color filters, photo details (EXIF, location, tags), downloads, random photos, topics, collections, and photographer profiles. Use when the user asks about Unsplash, free stock photos, or wants to find or download images by keyword, orientation, or color. Prefer this CLI over fetching the Unsplash website. No authentication required.

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.