Wallpapers from Unsplash: Terminal commands and Alfred workflow

A collection of Terminal commands and an Alfred workflow that allow Mac users to replace their desktop background(s) with photos from the popular Unsplash.com.

What’s Included?

  • Alfred workflow
  • Terminal commands and alias utilizing an AppleScript via the command line


REQUIRED! — Rename Directory
 After downloading the source files, YOU MUST rename the Wallpapers-from-Unsplash-master directory that is created when you download this repository.

The folder must be renamed Wallpapers-from-Unsplash

After renaming the folder Wallpapers-from-Unsplash you may relocate the folder anywhere you’d like on your Mac (within your user account).

Alfred Workflow

Install the ‘Wallpapers-from-Unsplash’ Alfred workflow simply by double-clicking the Wallpapers-from-Unsplash.alfredworkflow file. Once installed, the Alfred workflow allows for 10 different keyword methods, along with 3 configuration methods.

Alfred Keywords

The keywords listed below trigger different actions within the Alfred workflow. If a keyword is followed by an argument (indicated below within brackets), the argument must follow the specified format.

  • unsplash
    Replaces the desktop background(s) with a random photo from Unsplash.
  • featured
    Replaces the desktop background(s) with a random featured photo from Unsplash.
  • search [comma-separated string of keywords]
    Replaces the desktop background(s) with a random photo matching the search keyword(s) from Unsplash. Separate keywords with commas and NO spaces.
    Example: search sunrise,city
  • category [valid category string]
    Replaces the desktop background(s) with a random photo from the specified category from Unsplash. Available categories: buildings, food, nature, people, technology, objects. 
    Example: category buildings
  • collection [collection id]
    Replaces the desktop background(s) with a random photo from the specified collection from Unsplash. 
    Example: collection 165921
  • username [username string]
    Replaces the desktop background(s) with a random photo from the specified user’s photos from Unsplash.
    Example: username stvcrtr
  • fetch [photo id]
    Replaces the desktop background(s) with a specified photo from Unsplash.
    Example: fetch KqVHRmHVwwM
  • desktop [desktop number]
    Replaces the desktop background specified by the integer with a random photo from Unsplash.
    Example: desktop 2
  • save [desktop number]
    Saves the current desktop background specified by the integer to the Wallpapers-from-Unsplash/images/saved-wallpapers/ directory.
    Example: save 2
  • load
    Replaces the current desktop background(s) with a random saved photo from Wallpapers-from-Unsplash/images/saved-wallpapers/

Alfred Configuration Keywords

  • setpath [Wallpapers-from-Unsplash]
    Sets the path of the Wallpapers-from-Unsplash/ directory. Type the keyword setpath followed by Wallpapers-from-Unsplashand then select the correct folder in Alfred.
    Required Usage: setpath Wallpapers-from-Unsplash
  • setdesktopwidth [integer]
    Sets the desktop width at which to download photos. Default is 2560.
    Example: setdesktopwidth 2560
  • setdesktopheight [integer]
    Sets the desktop height at which to download photos. Default is 1440.
    Example: setdesktopheight 1440

Bash Commands and Alias for Terminal

Once you have downloaded the repository and saved to your Mac, you can set up a shortcut (an alias) to also change the desktop background(s) via Terminal (bash) commands. To set up, open Terminal on your Mac and execute the following commands:

# go to your home directory 
$ cd
# Open your Mac's .bash_profile in the editor of your choice. 
# In this example, I open .bash_profile with Sublime Text.
# If a .bash_profile does not exist, you can first create
# one by running: $ cd ~/ && touch .bash_profile
$ open -a "Sublime Text" .bash_profile

Insert and save the following lines at the bottom of your .bash_profile. You will need to edit the path preceding the unsplash.scpt file to match the directory where you saved the repository. Note the ~/ before the start of the path that must be included. The easiest way to attain the path is to drag the Wallpapers-from-Unsplash folder icon onto your Terminal window. Replace /Users/username/ with ~/ so that the final result looks similar to this:

alias unsplash="osascript ~/Dropbox/Development/Wallpapers-from-Unsplash/unsplash.scpt"

Now you may easily run the script from the command line with the unsplash command followed by any of the commands listed in the table above. Some commands are slightly different than the Alfred equivalent, so refer to the help screen below. You may view the info any time below by running unsplash --help on the command line:

$ unsplash --help
# You may use the command 'unsplash' on it's own
# to fetch random wallpapers for your desktop(s).
# Alternatively, you may use one of the following
# arguments for more options:
# $ unsplash
# $ unsplash featured
# $ unsplash search [keyword,keyword]
# $ unsplash category [category id]
# $ unsplash collection [collection id]
# $ unsplash username [username]
# $ unsplash fetch [photo id]
# $ unsplash desktop [desktop #]
# $ unsplash save [desktop #]
# $ unsplash load
# You may set your desktop dimensions by
# using 'width' and 'height'.
# $ unsplash width [integer]
# $ unsplash height [integer]
# To view this info again, use $ unsplash --help


If installing the AlfredApp workflow, do I need to have the Alfred Powerpack?

You must purchase the Alfred Powerpack in order to add custom workflows.

If I just want to utilize the Terminal commands, do I need to be an Alfred user?

Just check out the Bash Alias for Terminal section to get started.

I’m not a “power-user” and am unfamiliar with using Terminal or command line tools. Is this for me?

The installation and usage instructions outlined below are simple and should have you up and running in minutes! Have a question? No problem, I’m here to help. Check out the Support section on how to get in touch.

Why must I rename the Wallpapers-from-Unsplash-master directory?

Because of the methods used to fetch, store, and load photos from the Unsplash API as well as from your local machine, the directory name must be changed to Wallpapers-from-Unsplash and remain the same (and hopefully unique) in order to ensure proper file handling. This becomes increasingly important if you are an Alfred user who sync’s workflows across multiple computers (via Dropbox, etc.).

I’m using the Alfred workflow and ran one of the commands, but I’m receiving an error. What happened? What can I do to fix?

Many things can happen that could cause an error. It’s possible the project was unable to reach the Unsplash API (however unlikely unless you’re behind a network proxy). The easiest fix to try is simply waiting 30 seconds, and trying the command again.
If the issue persists, here’s some things to try:
1. Make sure your machine isn’t behind a network firewall or proxy that prevents it from freely accessing the web.
2. Run the setpath command (if issue is with the Alfred workflow) as described in the table above.
3. Within the project directory, make a copy of the saved-wallpapers folder (including any files inside). Next, delete the workflow from Alfred, as well as the project’s Wallpapers-from-Unsplash folder. Download a fresh copy of the project and then follow the installation instructions above. Finally, replace the new saved-wallpapers folder within the project with the one you copied earlier. The project should now run successfully.
If you’re still having problems, open an issue and I’ll be glad to help!


Do you have questions? Would you like to contribute? Something else? Feel free to fork the project, open an issue, or submit a pull request.

Not into looking at code? No worries. Reach out on Twitter @adamdehaven.


Released under the MIT License.

Originally published at adamdehaven.com on April 8, 2016.