Command-line wallpaper downloader for wallhaven.cc, written in Rust.
Usage: whdl [OPTIONS] --query <QUERY>
Options:
-q, --query <QUERY> Query to search for
-R, --ratios <RATIOS> Aspect ratio filter, comma-separated (e.g. 16x9,16x10)
-r, --resolution <RESOLUTION> Exact resolution filter, comma-separated (e.g. 1920x1080)
-a, --atleast <ATLEAST> Minimum resolution (e.g. 1920x1080)
-p, --purity <PURITY> 100/110/111 (sfw/sketchy/nsfw) [default: 100]
-c, --category <CATEGORY> 100/010/001 or combined (general/anime/people) [default: 111]
-s, --sorting <SORTING> date_added, relevance, random, views, favorites, toplist [default: date_added]
-o, --order <ORDER> desc, asc [default: desc]
-C, --colors <COLORS> Dominant color filter (hex without #, e.g. 660000)
-P, --page <PAGE> Fetch a specific page of results (conflicts with --count)
-n, --count <COUNT> Total wallpapers to download; fetches multiple pages as needed (conflicts with --page)
-d, --directory <DIRECTORY> Output directory [default: current directory]
-j, --jobs <JOBS> Maximum concurrent downloads [default: 4]
--dry-run Print what would be downloaded without saving any files
-h, --help Print help
-V, --version Print version
Search and download from the first page:
whdl -q "Cyberpunk 2077" -p 100 -r 1920x1080 -c 110 -R landscape
Download 72 wallpapers (fetches 3 pages automatically):
whdl -q "nature" -n 72 -a 2560x1440 -d ~/wallpapers
Browse a specific page:
whdl -q "space" -P 3 -s views
Preview results without downloading:
whdl -q "abstract" --dry-run
Wallhaven returns 24 results per page. --page fetches a single specific
page. --count calculates how many pages are needed to satisfy the requested
total, fetches them concurrently, and truncates to exactly the number asked
for. The two flags conflict and cannot be used together.
An API key is required to access NSFW content or your own account’s collections. The application reads it from the environment:
export WALLHAVEN_API_KEY=your_key_here
Keys can be generated at https://wallhaven.cc/settings/account. Full API documentation is available at https://wallhaven.cc/help/api.
Downloaded files are saved as wallhaven-<id>.jpg or wallhaven-<id>.png
depending on the source format. Re-running the same query skips any files
that already exist in the output directory.