Skip to content
Wallpaper Server Wallpaper Server Docs

Shell and Cron

The shell is the simplest way to use Wallpaper Server. This guide uses a placeholder host of your-server; replace it with your server’s address (for example localhost:8519).

A safe download

Section titled “A safe download”

Download into a temporary file first, and only replace your wallpaper if the request succeeded. This avoids overwriting a good wallpaper with an empty or error response.

#!/usr/bin/env sh
set -eu


url="http://your-server:8519/api/wallpapers/random/image?brightness=dark"
tmp="$(mktemp -t wallpaper.XXXXXX)"


if curl --fail --silent "$url" --output "$tmp"; then
  mv "$tmp" "$HOME/.local/share/wallpaper/current.jpg"
  # Apply it with your platform's wallpaper command, for example:
  # gsettings set org.gnome.desktop.background picture-uri "file://$HOME/.local/share/wallpaper/current.jpg"
else
  rm -f "$tmp"
  echo "Wallpaper request failed" >&2
  exit 1
fi

Notes:

  • --fail makes curl return a non-zero exit code on HTTP errors (such as a 404 when no wallpaper matches your filters).
  • The URL is quoted so the shell does not treat & as a job separator.
  • The wallpaper-setting command depends on your desktop environment and is left as a comment — GNOME, KDE, macOS and others each have their own.

Scheduling with cron

Section titled “Scheduling with cron”

Change the wallpaper every hour:

0 * * * * /home/you/bin/change-wallpaper.sh

For desktop sessions, a systemd user timer or your desktop’s autostart may be more reliable than cron, because cron jobs often lack the environment needed to talk to the running desktop session.

Section titled “Related”