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

Wallheaven is a CLI tool for fetching random wallpapers from [wallhaven.cc](https://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](https://chromewebstore.google.com/detail/wallheaven/iokjhndjbphfgllcgkbpmcoojiceegap).  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](/assets/thumb_link.png)

Wallpaper thumbnail link when hovering over thumbnails

![wallpaper info link](/assets/page_link.png)

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](https://github.com/davenicholson-xyz/wallheaven/releases)

---

### 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](https://github.com/davenicholson-xyz/wallheaven/blob/main/examples/config.toml)

---

### 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](/examples/setwallpaper.sh)