/unsplash-cli

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`, then run `python -m camoufox fetch` once.

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.