Pexels CLI (Rust)

Agent-optimized CLI for the Pexels API.

Hard fork of agynio/pexels-cli.

Install

• Build from source: cargo install --path pexels

Auth

• Env: PEXELS_TOKEN (or PEXELS_API_KEY); fallback order: PEXELS_TOKEN → PEXELS_API_KEY.
• Config file: ~/.config/pexels/config.yaml (or OS equivalent). Run pexels auth login: it reads PEXELS_TOKEN/PEXELS_API_KEY if set, otherwise prompts (or reads stdin, e.g. echo "$KEY" | pexels auth login). The key is never accepted as a CLI argument.

Usage examples

• pexels auth status
• pexels photos search -q cats
• pexels photos curated
• pexels videos popular
• pexels collections featured

Downloads

• pexels photos download <id> <path> saves src.original. Add --size on photos search/photos url to pick another src.* variant (original, large2x, large, medium, small, portrait, landscape, tiny).

• pexels videos download <id> -o <path> inspects video_files and downloads the best match. Filters: --quality (sd/hd/uhd), --orientation (landscape/portrait/square, derived from width vs height), --max-width <px>, --prefer <substring> (matched against file_type, default mp4 so HLS playlists aren't picked by accident).

• Both downloads stream straight to a <path>.part file, fsync, then atomically rename into place — a dropped connection never leaves a truncated file at <path>.

• Pass - as the id to read the resource's JSON from stdin instead of fetching it from the API — saves the metadata request when you already have the object (e.g. from a prior search --raw):

  pexels videos search "cats" --raw | jq -c '.videos[0]' | pexels videos download - -o cat.mp4

• photos search/videos search accept --download <dir> to save every result in one command (same filters as above), using only the one API request the search itself made: pexels videos search "cats" --download ./out --max-width 1280. Per-item failures are collected in the output instead of aborting the batch. (get --download doesn't exist: for a single id that's exactly what download <id> already does.)

• --timeout (default 15s) governs JSON API calls; --download-timeout (default 120s) governs asset downloads only, since large video files need longer than a metadata call.

Pagination

• --all (with --limit/--max-pages) fetches multiple pages by re-issuing the request with an incremented page, not by following the next_page URL the API returns — that URL has shipped malformed (a duplicated /v1/ segment) on both photos and videos search.

Output

• Successful outputs are wrapped as { data: <payload> } for single-resource outputs, and { data: <items[]>, meta: { total_results?, next_page?, prev_page?, request_id? } } for list endpoints.
• For list endpoints, data is the items array (photos/videos/collections/media). For single-resource endpoints, data is the object and meta is omitted.
• page/per_page are omitted. next_page/prev_page are integers (page numbers) or null.
• Field selection via --fields supports dot paths and sets: @ids,@urls,@files,@thumbnails,@all.
• Some fields are omitted by default for lighter responses; include heavy fields via --fields.

Testing

• Unit tests cover projection, config precedence, error mapping, and page parsing.
• Live tests run in CI when PEXELS_TOKEN is present and event is safe. Commands:
  • pexels auth status
  • pexels photos search -q cats
  • pexels photos curated
  • pexels videos popular
  • pexels collections featured

CI/Release

• CI runs: lint -> unit tests -> build -> live tests (guarded by secrets.PEXELS_TOKEN and internal PRs/main).
• On push to main, a release tag is created and binaries for Linux/macOS/Windows are uploaded.