Unsplash Image Search & Download

Search Unsplash for images, download them, and optionally add text overlay.

Tool Location

• Script: ~/.agents/tools/unsplash-search.py
• Env file: ~/.agents/tools/.env (contains UNSPLASH_CLIENT_ID)

Quick Usage

Search and download a random matching image

python ~/.agents/tools/unsplash-search.py \
  --query "nature landscape" \
  --output ./image.jpg

With orientation filter

python ~/.agents/tools/unsplash-search.py \
  --query "coffee shop" \
  --orientation landscape \
  --output ./coffee.jpg

With text overlay (title and subtitle)

python ~/.agents/tools/unsplash-search.py \
  --query "technology abstract" \
  --output ./cover.png \
  --title "My Blog Post Title" \
  --subtitle "A short description"

List results without downloading

python ~/.agents/tools/unsplash-search.py \
  --query "sunset" \
  --list

Pick the first result instead of random

python ~/.agents/tools/unsplash-search.py \
  --query "mountains" \
  --pick first \
  --output ./mountains.jpg

CLI Options

Option	Description
--query, -q	(Required) Search query string
--output, -o	(Required unless --list) Output file path
--orientation	Filter: landscape, portrait, or squarish
--color	Color filter (e.g., blue, green, red, black_and_white)
--pick	How to select from results: random (default) or first
--title	Title text to overlay on the image
--subtitle	Subtitle text to overlay (only used with --title)
--list	List search results instead of downloading
--count	Number of results to fetch, max 30 (default: 30)

Text Overlay