April 8, 2016

Wallpapers from Unsplash - A command line prompt and Alfred App workflow

A command line prompt and Alfred workflow that allow Mac users to replace their desktop background(s) with photos from the popular Unsplash.com

What's Included?

Alfred workflow
Command line prompt utilizing an AppleScript via the command line

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

Download the project

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

Install the Alfred Workflow

Install the 'Wallpapers-from-Unsplash' Alfred workflow simply by double-clicking the Wallpapers-from-Unsplash.alfredworkflow file.

Set up the command line prompt

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 the command line. To set up, open Terminal (or other command line shell) on your Mac and execute the following commands:

# Open your Mac's .bashrc in the editor of your choice.
# In this example, I open .bashrc with Visual Studio Code.
code ~/.bashrc

# If the .bashrc file does not exist, you can first create it by running:
cd ~/ && touch .bashrc
# Then open the file
code ~/.bashrc

Insert and save the following lines in your .bashrc file. 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 into your command line window. Replace /Users/username/ with ~/ so that the final result looks similar to this:

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

Usage

Alfred Workflow

Once installed, the Alfred workflow allows for 11 different keyword methods, along with 3 configuration methods.

KEYWORD	ARGUMENT	DESCRIPTION
`unsplash`	none	Replaces the desktop background(s) with a random photo from Unsplash
`featured`	none	Replaces the desktop background(s) with a random featured photo from Unsplash
`search`	`comma-separated keyword(s)`	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`
`collection`	`collection id`	Replaces the desktop background(s) with a random photo from the specified collection from Unsplash. *Example:* `collection 165921`
`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`	`integer`	Replaces the desktop background specified by the `integer` with a random photo from Unsplash. *Example:* `desktop 2`
`save`	`integer`	Saves the current desktop background specified by the `integer` to the `Wallpapers-from-Unsplash/img/saved-wallpapers/` directory. *Example:* `save 2`
`saved`	`string`	Replaces the current desktop background(s) with a specific saved photo from your `Wallpapers-from-Unsplash/img/saved-wallpapers/` directory. You may pass a full or partial image name. *Example:* `saved TZCehSn-T-o`
`load`	none	Replaces the current desktop background(s) with a random saved photo from `Wallpapers-from-Unsplash/img/saved-wallpapers/`
USER	CONFIG	METHODS
`setpath`	`Wallpapers-from-Unsplash`	Sets the path of the `Wallpapers-from-Unsplash/` directory. Type the keyword `setpath` followed by `Wallpapers-from-Unsplash`and 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:* `setdesktopwidth 2560`
`setdesktopheight`	`integer`	Sets the desktop height at which to download photos. *Default:* `setdesktopheight 1440`

Command Line Prompt

After installing, you may easily run the command line prompt 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 collection [collection id]
#       unsplash username [username]
#       unsplash fetch [photo id]
#       unsplash desktop [desktop #]
#       unsplash save [desktop #]
#       unsplash saved [full or partial image name]
#       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
#

FAQ

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

Yes

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

If I just want to utilize the command line prompt, do I need to be an Alfred user?

Nope

Just check out the Command Line Prompt section to get started.

I'm not a "power-user" and am unfamiliar with using command line tools. Is this for me?

Yes!

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 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 are a few things to try:

Make sure your machine isn't behind a network firewall or proxy that prevents it from freely accessing the web. If you are behind a firewall or proxy (e.g. while you're at work), there's probably an issue with outgoing ports or accessing the unsplash.com or adamdehaven.com domains.
Run the setpath command (if issue is with the Alfred workflow) as described in the table above.
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!

Support

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.