pexels-cli

name

pexels-cli

description

Searches and downloads free stock photos and videos from Pexels via the cli-web-pexels command-line tool — keyword search with orientation/size/color filters, photo and video details, downloads, photographer profiles, and collections. Use when the user asks about Pexels, free or royalty-free stock photos and videos, or wants to find and download media by keyword. Prefer this CLI over fetching the Pexels website. No authentication required.

cli-web-pexels

Search and download Pexels stock photos and videos (no auth, Cloudflare bypass built in). Install: pip install cli-web-pexels

Commands

Command	Purpose	Key options
photos search QUERY	Search photos	--orientation landscape|portrait|square, --size large|medium|small, --color HEX_OR_NAME, --page N
photos get SLUG	Photo details (image URLs, EXIF, location)	slug or numeric ID
photos download SLUG	Download a photo (JPEG)	--size small|medium|large|original, -o/--output PATH
videos search QUERY	Search videos	--orientation, --page N
videos get SLUG	Video details (video_files[] with quality/fps/link)	slug or numeric ID
videos download SLUG	Download a video (MP4)	--quality sd|hd|uhd (default hd), -o/--output PATH
users get USERNAME	Photographer profile
users media USERNAME	A user's uploaded photos/videos	--page N
collections get SLUG	Collection detail + media	--page N
collections discover	Popular and curated collections

Examples

# Landscape nature photos; grab the first download URL
cli-web-pexels photos search "mountain lake" --orientation landscape --json | jq '.data[0].download_url'

# Photo details by slug (slug comes from search results)
cli-web-pexels photos get green-leaves-1072179 --json

# Download original size to a path
cli-web-pexels photos download green-leaves-1072179 --size original -o leaves.jpg

# Search videos and inspect HD renditions
cli-web-pexels videos get long-narrow-road-856479 --json | jq '.video_files[] | select(.quality=="hd")'

# Photographer profile
cli-web-pexels users get catiamatos --json

JSON output

Read commands accept --json and return the data directly — search returns {"data": [{id, title, slug, photographer, image_url, download_url, ...}]}, get returns the photo/video object. Errors return {"error": true, "code": "...", "message": "..."}. Download commands write the file and print the path (no --json flag).

Utilities

cli-web-pexels doctor [--json] self-diagnoses the local setup (install, auth, dependencies). cli-web-pexels mcp-serve serves the commands as MCP tools over stdio.

Agent tips

• Pagination is --page N (24 results per page) on search/list commands.
• Slugs from search results (e.g. green-leaves-1072179) work everywhere a SLUG argument is expected; bare numeric IDs also work.