splash-cli: Unsplash wallpapers on your desktop from the terminal

A wallpaper setter with a filter language

splash-cli is described as a simple CLI to download Unsplash wallpapers, with the tagline that nothing fancy is going on and it simply works, and the topic tags confirm the scope, covering wallpapers, change-wallpaper, download-photos, photography and beautiful-photos. The project description is the shortest statement of the idea, and it is a good one, since the tool takes the thing you would do in a browser, find a photo you like and set it as your desktop background, and reduces it to a command. What makes it more than a wrapper is the filter set, which is documented in the help output. There is a day flag to retrieve the photo of the day, a query flag to limit the selection to photos matching a search term, an orientation filter that defaults to a wide format, collections and topics flags for public collection and topic IDs, and a user flag to limit the selection to a single user. On top of that there are flags that control what happens to the result, with a save flag to save the photo without setting it as wallpaper, a no-cache flag, a plain flag for plain output that is good for a tty, a scale flag defaulting to auto, and a screen flag for setting the wallpaper on a specific monitor that is marked macOS only and defaults to negative one.

Installing it, and the credential problem

There are three install routes and one requirement in common. The Homebrew route taps a third party tap and installs the binary.

brew tap rawnly/tap
brew install splash-cli

The Go route installs the module directly.

go install github.com/rawnly/splash-cli@latest

The manual route is to download the latest pre-release from the releases page and move the binary into your path. The README warns about one naming detail for the Go route, that the binary name is splash-cli and not splash when installing via go, which is a small trap given that the command you then run is splash. The credential requirement is the real setup cost. The required environment variables are UNSPLASH_CLIENT_ID and UNSPLASH_CLIENT_SECRET, and you get the credentials from the Unsplash Developer Portal, which means registering an application and getting a client id and secret. The project is built on cobra and viper, so the environment variables are read through viper's configuration, and there is an auth command for authenticating with Unsplash, which suggests the flow goes further than a bare API key once you want user-level features. The tips in the README are about the binary name and the credentials rather than about the flags, which is a reasonable signal about where the friction is.

Subcommands, and the flag set in full

The command structure is cobra shaped, so the flags belong to the root command and the subcommands are separate capabilities. The available commands are alias for managing collection aliases, auth for authenticating with Unsplash, collection for CRUD on collections, completion for generating the autocompletion script for the specified shell, help, and settings for managing user settings. The root flags are the ones that shape a single fetch, and the help output lists them with their defaults.

  -c, --collections strings   Public collection ID(s) to filter selection. If multiple, comma-separated
      --day                   Retrieve the photo of the day
  -h, --help                  help for splash
      --id string             Retrieve a single photo by ID
      --no-cache              Ignore cache
      --plain                 Plain output. Good for tty
  -q, --query string          Limit selection to photos matching a search term.
  -s, --save                  Save the photo without setting it as wallpaper
      --scale string          Set wallpaper scale (default "auto")
      --screen int            Set wallpaper on a specific screen. (macos only) (default -1)
  -t, --topics strings        Public topic ID(s) to filter selection. If multiple, comma-separated
  -u, --user string           Limit selection to a single user.

Two defaults are worth noticing. The orientation default means an unqualified call gives you a wide photo, which on a portrait monitor is a crop you did not ask for, and the scale default of auto leaves the sizing to the platform. The cache flag implies the tool keeps a local cache of what it has already downloaded, which is what makes a repeated call cheap and a scheduled job fast, and no-cache is the escape hatch when you want to force a fresh fetch. The two example invocations in the help output are minimal, one for the photo of the day and one for a query with an explicit orientation.

The dependency list explains what the tool actually does

The go.mod is more informative than the README about the internals, and it shows a Go binary assembled from well-known pieces. The command line is cobra with viper for configuration and cast for typed flag values, and the logging stack is unusual for a project of this size, since zerolog and logrus appear together alongside mgutz/ansi, which suggests the terminal output is styled rather than plain. The survey library from AlecAivazis provides interactive prompts, which fits a tool that asks the user to pick a photo and offers a set of choices, and the spinner library gives progress feedback during a download. The wallpaper itself is applied through rawnly/go-wallpaper, the same author's separate package, and the browser library from cli/browser is there to open a result in a browser, with eiannone/keyboard for keypress handling in that interactive flow. The blurhash package computes a blurhash, which is the compact representation of an image that can be shown as a placeholder while the full photo downloads. The uuid package, the shellescape package and the go-keyring package point at a tool that can write files to disk, escape arguments when shelling out, and store a credential in the operating system keychain, and the sentry-go and posthog-go dependencies are the clearest thing in the file, since they mean the tool reports crashes and usage events to those two analytics services.

Building locally, with a Nix flake and a mise toolchain

The build section is short and assumes GoReleaser, which is the standard for a Go command line tool that ships binaries for several platforms. The release configuration lives in a .goreleaser.yaml at the top of the repository, and the snapshot command builds without publishing.

    goreleaser --snapshot --rm-dist
    
    # Or
    
    make build # this will only build for the current platform

The repository also carries a flake.nix and a flake.lock, so a Nix user can build it in a pinned environment, and a mise.toml for the same purpose with mise, plus a lefthook.yml for git hooks, which is the Go equivalent of the pre-commit setups common elsewhere. The setup.go file at the top level is a conventional Go convention for build-time setup steps. A note in the README is worth reading because it is a footgun in a different place: if you have an .env file in your project root, make will automatically inject those values into script commands. That is convenient for local development, and it is also a behaviour to be aware of, because an .env file holding an Unsplash client secret will be handed to every make target you run. The top level of the repository also holds a demo script, a config/ directory, an unsplash/ package for the API client, a lib/ directory, a cmd/ directory and a __tests__ directory, so the project is laid out as a normal multi-package Go module with tests alongside.

Where splash-cli is the wrong tool

The honest assessment is that this is a convenience wrapper, and convenience wrappers have a cost. The first limitation is that it only works for a specific service, so if you want wallpapers from a source other than Unsplash, the tool does nothing for you, and if your interest is photography as a hobby rather than as a wallpaper source, the browsing experience of Unsplash itself is better than a terminal filter. The second is the dependency on your own API credentials and on that API's terms, since a registered application key is subject to a rate limit and a usage policy, and a scheduled job that runs every hour will consume that quota whether or not you are looking at the results. The third is the analytics and error reporting in the dependency list, which is a decision made by the author rather than by you, and it is the kind of thing to consider if you run a tool on a machine where you would not expect network calls. The fourth is platform coverage, since setting a wallpaper is a different operation on macOS, on Windows and on Linux desktops, and the screen flag is explicitly macOS only, which tells you the multi-monitor case is at best partial. The last is the licensing, since the project listing records no recognised licence, so there is no stated permission for redistribution or for embedding the binary in something else, which is a fine position for a personal tool and a poor one for anyone building on it.

Editorial conclusion

Adopt splash-cli if you want a fresh wallpaper on a schedule, if you like pulling photos by query, collection, topic or photographer rather than picking from a browser, and if you are comfortable registering an Unsplash application for API credentials. Skip it if a browser tab and the right click menu already do the job, since this is a convenience rather than a capability difference. Verify first that your Unsplash client id and secret are exported as environment variables, that the machine you run it on is one where setting a wallpaper is meaningful, and that the orientation default does not fight your screen shape.

Frequently asked questions

Official sources

1. Issues
2. rawnly/splash-cli on GitHub
3. README
4. Releases