cli-web-unsplash

CLI for searching and discovering photos on Unsplash. Installed at: cli-web-unsplash.

Quick Start

# Search for photos
cli-web-unsplash photos search "mountains" --json

# Get photo details
cli-web-unsplash photos get SyfvrXRy28Y --json

# Browse topics
cli-web-unsplash topics list --json

Always use --json when parsing output programmatically.

Commands

photos search <query>

Search photos by keyword with optional filters.

cli-web-unsplash photos search "sunset" --orientation landscape --color orange --per-page 10 --json

Key options: --orientation (landscape/portrait/squarish), --color, --order-by (relevant/latest), --page, --per-page Output fields: total, total_pages, results[] with id, description, width, height, likes, color, author, url, link, premium

photos get <photo_id>

Get full photo details including EXIF, location, and tags.

cli-web-unsplash photos get SyfvrXRy28Y --json

Output fields: id, slug, description, width, height, color, likes, views, downloads, created_at, author ({username, name}), urls, exif (camera, aperture, exposure, focal_length, iso), location (name, city, country, latitude, longitude), tags[], premium, link

photos random

Get random photo(s), optionally filtered.

cli-web-unsplash photos random --query "nature" --count 3 --orientation landscape --json

photos download <photo_id>

Download a photo to disk.

cli-web-unsplash photos download Bkci_8qcdvQ --size full -o mountain.jpg --json

Key options: --size (raw/full/regular/small/thumb, default: full), --output / -o (file path) Output fields (JSON): photo_id, size, file, bytes, description

photos stats <photo_id>

Get photo view and download statistics.

cli-web-unsplash photos stats SyfvrXRy28Y --json

topics list

List available photo topics.

cli-web-unsplash topics list --json

topics get <slug>

Get topic details.

cli-web-unsplash topics get nature --json

topics photos <slug>

List photos in a topic.

cli-web-unsplash topics photos nature --per-page 10 --order-by popular --json

collections search <query>

Search photo collections.

cli-web-unsplash collections search "wallpapers" --json

collections get <id>

Get collection details.

cli-web-unsplash collections get 1065976 --json

collections photos <id>

List photos in a collection.

cli-web-unsplash collections photos 1065976 --per-page 10 --json

users search <query>

Search users by name.

cli-web-unsplash users search "landscape" --json

users get <username>

Get user profile.

cli-web-unsplash users get unsplash --json

users photos <username>

List photos by a user.

cli-web-unsplash users photos unsplash --order-by popular --json

users collections <username>

List collections by a user.

cli-web-unsplash users collections unsplash --json

Agent Patterns

# Find landscape photos of mountains and get the first result's details
cli-web-unsplash photos search "mountains" --orientation landscape --per-page 1 --json | python -c "import json,sys; d=json.load(sys.stdin); print(d['results'][0]['url'])"

# Get a random nature photo URL
cli-web-unsplash photos random --query "nature" --json | python -c "import json,sys; d=json.load(sys.stdin); print(d[0]['url'])"

# Find a photographer's top photos
cli-web-unsplash users photos unsplash --order-by popular --per-page 5 --json

# Search and download the first result
ID=$(cli-web-unsplash photos search "sunset beach" --per-page 1 --json | python -c "import json,sys; print(json.load(sys.stdin)['results'][0]['id'])")
cli-web-unsplash photos download "$ID" --size regular -o sunset.jpg

Notes

• Auth: Not required — all endpoints are public
• Rate limiting: Generous limits (x-ratelimit-limit: 99999999)
• Premium photos: Some results have premium: true (Unsplash+ only)
• Image URLs: Use urls.regular for web-quality, urls.raw for full resolution