Quick Start

This guide takes you from a built binary to one wallpaper returned over HTTP. It assumes you have already installed the server.

Create a configuration file at the default location and point it at a folder of images.
Terminal window
```
mkdir -p ~/.config/wallpaper-server
```
~/.config/wallpaper-server/config.yaml
```
server:
  host: 0.0.0.0
  port: 8519
wallpaper_folders:
  - /path/to/your/wallpapers
```
Replace /path/to/your/wallpapers with a directory containing .jpg, .jpeg, .png or .webp files.
Start the server. The --start flag is required.
Terminal window
```
./wallpaper-server --start
```
On startup the server scans your folders, analyses each image and builds its index. The first scan of a large library can take a moment.
Fetch a random wallpaper as an actual image file:
Terminal window
```
curl "http://localhost:8519/api/wallpapers/random/image" --output wallpaper.jpg
```
The response body is the image itself, so save it straight to disk.
Open the gallery in a browser to see your library:
```
http://localhost:8519/
```

Try a filter. Ask for a dark, landscape wallpaper:

curl "http://localhost:8519/api/wallpapers/random/image?brightness=dark&orientation=landscape" \
  --output dark-landscape.jpg

What next

Filtering wallpapers — combine brightness, size, aspect ratio, colour and format.
Configuration — cache and upload locations, supported formats and more.
Automation — schedule wallpaper changes from the shell, a phone or your home automation setup.