---
name: Unsplash CLI
slug: unsplash-cli
category: Automation
description: Unsplash CLI searches, browses, and downloads Unsplash photos from the command line. Use it to find images by keyword, filter by orientation or color, and inspect photo details, topics, collections, and profiles.
github: "https://github.com/ItamarZand88/CLI-Anything-WEB/tree/main/.claude/skills/unsplash-cli"
language: Python
stars: 215
forks: 45
install: "npx degit https://github.com/ItamarZand88/CLI-Anything-WEB/tree/main/.claude/skills/unsplash-cli ~/.claude/skills/unsplash-cli"
installs_to: ~/.claude/skills/unsplash-cli
source_path: .claude/skills/unsplash-cli/SKILL.md
collection_size: 25
category_size: 1860
collection_url: "https://dirskills.com/collections/ItamarZand88/CLI-Anything-WEB"
added: 2026-09-04T05:25:50.489Z
last_synced: 2026-09-04T05:25:50.489Z
canonical_url: "https://dirskills.com/skills/unsplash-cli"
---

# Unsplash CLI

Unsplash CLI searches, browses, and downloads Unsplash photos from the command line. Use it to find images by keyword, filter by orientation or color, and inspect photo details, topics, collections, and profiles.

**Install:**

```bash
npx degit https://github.com/ItamarZand88/CLI-Anything-WEB/tree/main/.claude/skills/unsplash-cli ~/.claude/skills/unsplash-cli
```

## README

# 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

```bash
# 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.