Skip to content
Wallpaper Server Wallpaper Server Docs

CLI Guide

Wallpaper Server has one Go binary with two roles: wallpaper-server --start serves a library and web gallery, while wallpaper-server <command> operates as a local/remote API client. The commands below describe the development branch for issue #41, not a confirmed published release.

Quick start

Section titled “Quick start”
Terminal window
wallpaper-server status
wallpaper-server doctor
wallpaper-server list --limit 10
wallpaper-server search mountain --brightness dark
wallpaper-server random --orientation landscape --json
wallpaper-server download --output ./wallpaper.jpg --brightness dark
wallpaper-server apply --file ./wallpaper.jpg

For a remote library:

Terminal window
export WALLPAPER_SERVER_URL=https://wallpapers.example.com
export WALLPAPER_SERVER_ADMIN_TOKEN='your-long-random-secret'
wallpaper-server status
wallpaper-server upload ~/Pictures/example.png

Supply flags before positional arguments: search --brightness dark mountain, upload --server URL file.png, rotation status --json PROFILE_ID. The Go CLI uses subcommand-specific flags rather than one global flag set.

Browse, curate and transfer

Section titled “Browse, curate and transfer”
Task Example
List/paginate wallpaper-server list --page 2 --limit 25
Search wallpaper-server search --tag nature mountain
Random metadata wallpaper-server random --favorites --json
Download random wallpaper-server download --brightness dark --output ./dark.jpg
Download specific wallpaper-server download --id IMAGE_ID --output ./image.png
Upload wallpaper-server upload /path/to/photo.jpg
Favourite/unfavourite wallpaper-server favorite add IMAGE_ID / favorite remove IMAGE_ID
Tags wallpaper-server tag set --tags "landscape,blue" IMAGE_ID
Hide/unhide source wallpaper-server hide IMAGE_ID / unhide IMAGE_ID
Find hidden wallpaper-server hidden --json
Exact duplicates wallpaper-server duplicates --json
Similar images wallpaper-server similar --max-distance 5 IMAGE_ID
Create collection wallpaper-server collection create --name "Best" --ids IMAGE_ID,OTHER_ID
List/delete collections wallpaper-server collection list / collection delete COLLECTION_ID
Generate variant wallpaper-server variant --id IMAGE_ID --width 1920 --height 1080 --fit cover --output ./wide.jpg

Choose from --brightness, --orientation, --aspect-ratio, --hue, --format, --tag, --collection, --favorites, --min-width, --min-height, --max-width, --max-height, --sort and --search. list, search and random accept --json; other commands describe their own --json options. Downloads are written to a temporary file then atomically published on success.

Recoverable deletion

Section titled “Recoverable deletion”
Terminal window
wallpaper-server hide IMAGE_ID
wallpaper-server hidden
wallpaper-server unhide IMAGE_ID


# Managed uploads are moved to private trash on DELETE:
wallpaper-server trash list
wallpaper-server trash restore IMAGE_ID
wallpaper-server trash purge --confirm IMAGE_ID

Hiding a source image never removes its original; restoring a trashed managed upload rescans it. purge --confirm is irreversible. See Uploading and managing.

Desktop wallpaper and rollback

Section titled “Desktop wallpaper and rollback”
Terminal window
wallpaper-server apply --file ./wallpaper.jpg
wallpaper-server apply --id IMAGE_ID --monitor all
wallpaper-server next --apply --avoid-recent 10 --client my-desktop
wallpaper-server previous

Supported adapters are environment-dependent: macOS uses osascript and System Events (Automation permission required, 1-based desktop index); Windows uses SystemParametersInfoW for all displays only; Linux detects working awww, swww, hyprpaper, GNOME gsettings, xwallpaper or feh, depending on compositor and installed programs. Unsupported display/backend combinations fail explicitly; there is no promise of per-monitor support on every platform.

previous restores the previously applied local wallpaper recorded by this CLI, not an arbitrary operating-system history. Downloaded wallpapers are cached locally; a server outage does not delete files already downloaded, but a new remote selection still needs connectivity.

Scheduled rotation profiles

Section titled “Scheduled rotation profiles”
Terminal window
wallpaper-server rotation create --name "Evening" --interval-minutes 60 \
  --brightness dark --avoid-recent 10 --favorite-weight 6 --rating-weight 2 \
  --start-time 18:00 \
  --end-time 23:00 --timezone Europe/London
wallpaper-server rotation list
wallpaper-server rotation status PROFILE_ID
wallpaper-server rotation run --once PROFILE_ID
wallpaper-server rotation run PROFILE_ID
wallpaper-server rotation pause PROFILE_ID
wallpaper-server rotation resume PROFILE_ID
wallpaper-server rotation delete --confirm PROFILE_ID

The rotation run command is a local foreground worker: it fetches profiles and uses local platform adapters. To keep it running after logout, configure a user service or scheduler yourself. --dry-run previews eligible images without advancing history, --download-only fetches without changing the desktop, and --no-initial defers the first change until the next interval. Active windows use IANA timezone names and support midnight crossings. Rotation history is kept by the server per client. Within the least-selected eligible set, favourites and highly rated wallpapers receive greater selection weight; the least-used-first rule and recent-history exclusions prevent other eligible images from starving. Customise the bonuses per profile using --favorite-weight and --rating-weight (0–20 each); zero disables the corresponding bonus.

Bulk edits, device scoring and offline caches

Section titled “Bulk edits, device scoring and offline caches”
Terminal window
wallpaper-server bulk --ids ID1,ID2 --favorite=true --rating=4
wallpaper-server bulk --tags="night,calm" ID1 ID2
wallpaper-server cache sync --profile PROFILE_ID --limit 24 --max-cache-mib 1024
wallpaper-server cache status --profile PROFILE_ID
wallpaper-server cache verify --profile PROFILE_ID
wallpaper-server cache prune --profile PROFILE_ID --confirm
wallpaper-server rotation run --offline PROFILE_ID
wallpaper-server rotation run --offline --once --download-only PROFILE_ID
wallpaper-server cache clear --profile PROFILE_ID --confirm

Offline mode is explicit and does not contact the server or synchronize local history upstream. Download cached images while online before relying on a server outage. On Windows, apply --monitor 1 uses native per-monitor COM (Windows 8+); other backends have platform-specific limitations.

Advanced library guide covers stable IDs, monitoring, crop compatibility, bounded bulk edits and offline recovery.

Section titled “Private visual semantic search”

Semantic image search is optional, requires a locally installed Ollama multimodal embedding model, and never changes the server’s ordinary wallpaper API:

Terminal window
wallpaper-server semantic search \
  --model YOUR_LOCAL_MULTIMODAL_EMBEDDING_MODEL \
  --query "quiet misty mountains" --max-candidates 30 --limit 10 --json

Inference is restricted to a numeric loopback Ollama address. Thumbnail bytes are bounded, cloud-backed model entries are rejected, and results rank image/text embedding similarity rather than merely matching filenames. See Local semantic search for limitations.

Setup, diagnostics and completions

Section titled “Setup, diagnostics and completions”
Terminal window
wallpaper-server config init
wallpaper-server config validate --path ~/.config/wallpaper-server/config.yaml
wallpaper-server config show --path ~/.config/wallpaper-server/config.yaml
wallpaper-server doctor
wallpaper-server completion zsh
wallpaper-server completion bash
wallpaper-server completion fish
wallpaper-server completion powershell

config init refuses to overwrite an existing config. config validate loads the config and may create associated cache/log/data directories. status checks GET /api/health; doctor checks local configuration and attempts server connectivity.

Service flags remain supported:

Terminal window
wallpaper-server --start --config /path/to/config.yaml
wallpaper-server --version
wallpaper-server --autostart
wallpaper-server --restart
wallpaper-server --uninstall-service

Service installation/restart is systemd-specific on Linux.

Secure remote credentials

Section titled “Secure remote credentials”
Setting Effect
--server URL Use a remote HTTP(S) server origin
WALLPAPER_SERVER_URL Default server URL if no flag is supplied
WALLPAPER_SERVER_ADMIN_TOKEN Shared bearer token for privileged requests
WALLPAPER_SERVER_ALLOW_INSECURE_ADMIN=1 Explicitly allow sending a token to a remote plaintext HTTP URL; unsafe outside controlled networks

The CLI rejects non-loopback HTTP with an admin token by default. Use HTTPS with trusted certificates or a local SSH tunnel. Redirects that change scheme, hostname or port are not followed with credentials. Keep secrets out of shell arguments, Git repositories and logs. Read Security and remote access before enabling remote administrative access.

For exact request/response contracts see the Endpoint reference.