unsplash-image

name	unsplash-image
description	Search for images on Unsplash and download them. Optionally add text overlay (title/subtitle) to the image. Use when the user asks to find a stock photo, search for an image, get an Unsplash image, or download a photo with text.
argument-hint	["search query"]
allowed-tools	Bash(*), Read, Write

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