wallheaven

🌆 Wallheaven - Random wallpaper fetcher and setter for wallhaven.cc

Wallheaven is a CLI tool for fetching random wallpapers from wallhaven.cc. Wallheaven will randomly choose a wallpaper from various lists including your own collections using your API key. Wallheaven will set the wallpaper on your desktop on Windows, Mac and many Linux desktop environments.

Supported desktop environments

• Windows
• MacOS
• Linux
  • Gnome
  • Ubuntu
  • KDE Plasma
  • XFCE
  • Cinnamon
  • MATE
  • Budgie

Any unsupported can be manually set by passing a custom script. Feel free to raise an issue or a pull request for any missing environments.

All queries and selected wallpapers are cached to cut down on API calls.

New Chrome extension for wallhaven.cc

You can now select a wallpaper straight from the wallhaven.cc website using the chrome extension on the chrome web store. Run the wallheavend daemon on Linux/Mac or wallheavend.exe on Windows and a new button will appear on the wallpaper thumbnails and an extra button on the wallpaper info page.

Wallpaper thumbnail link when hovering over thumbnails

Sidebar link shown on wallpaper info page

Installation

Cargo cargo install wallheaven

Arch (AUR) yay -S wallheaven

Homebrew brew install davenicholson-xyz/tap/wallheaven

Download and install/build from the latest release

Configuration

Configuration is stored in $HOME/.config/wallheaven/config.toml on linux/mac or %appdata%/Roaming/wallheaven/config.toml on Windows. Wallheaven's defaults will be overwritten by these options, which in turn will be overwritten by any environment variables set proceeded with WALLHEAVEN_. These can then be overridden with any command line flags.

An example config.toml is in this here

Usage

Call the wallheaven command and select an option to retrieve a random wallpaper.

wallheaven -c collection_name will select a wallpaper from your collection with that name. Include your username and API key in the config/flags.

wallheaven -r search_term will return wallpapers from that query.

wallheaven -t to get a random wallpaper from the toplist. Pass a range option to search time range --range 1w will search the toplist for the past week.

wallheaven --hot will get wallpapers from the hottest wallpapers list.

Command line flags

--config [path]

Path to config file to use if not using default config path

--username [username]

wallhaven.cc username. Required to fetch from your collections

--apikey [apikey]

wallhaven.cc apikey to fetch NSFW images

-c --collection [name]

Name of collection to fetch random wallpaper from. Requires API key and username to be set

-r --random

Search query to select random wallpaper from

-t --toplist

Select a random image wallpaper from the most popular wallpapers in a time range

--range [1d, 3d, 1w, 1M, 3M, 6M, 1y] - Default 1M

The time range to select toplist wallpaper from. Default to 1M

--hot

Choose a random wallpaper from the most popular wallpapers right now!

-i --id [wallhaven id]

Sets wallpaper using the wallhaven.cc wallpaper ID

-p --purity [100,001,101 etc] - Default 110

Bits representing (sfw/sketchy/nsfw). Turn purities on(1) or off(0). NSFW requires a valid API key. Example: -p 100 will only return SFW images.

--categories [100,001,101 etc] - Default 111

Bits representing categories to search from (general/anime/people). Turn categories on(1) or off (0). Example: --categories 101 will not show anime images

--pages [1 - 10] - Default 3

Amount of pages to search for random toplist/hot image. Higher number = more API calls so slower.

-e --expiry [number] - Default 600

Time in seconds to use cached search results. After this time the API will be searched for new wallpapers.

-s --script [path]

Path to external script to call with path to downloaded image. Use to set desktop wallpaper.

-f --file

Returns the current file path of the last wallpaper set with wallhwaven

-u --url

Return the wallhaven.cc link to the last wallpaper set with wallheaven

-o --output

Return the wallpaper file path without setting the wallpaper

-l --last

Returns the last query made with --random

-d --delete

Deletes cache files

-h --help

Help file

-V --version

Version info

Setting wallpaper with external script

The wallheaven app sets the wallpaper depending on OS and desktop environment used. If yours is currently unsupported or you need a custom script you can set it using the post_script option in config.toml of via the -s --script flag (wallheaven -t -s "swww img")

You can also just pipe the output directly into a script.

wallheaven -t | swww img for example. Or if it does not allow piping feh --bg-fill $(wallhaven -t)

An example script to set the wallpaper on both Linux and Mac can be found here