Keyboard Maestro: Post to Pinboard from clipboard

July 10, 2011 by Gabe | [mmd] |

I’m really digging into the new features in Keyboard Maestro 5. In particular, there are some great new options for getting and setting variables. I figured that KM is now mature enough to return to some problems I never found an elegant solution for. And by elegant, I mean a solution that did not involve a huge AppleScript.

The first thing I focused on was a system wide function to take a url from the clipboard and post it to I’ve wanted this for awhile and I decided it was a good excuse to learn more about KM5.

Here’s what I developed1:

Copy a url anyone on the mac to the clipboard. Run the macro and new bookmark is added to your bookmarks with optional tags and the correct page title.

The key work of posting the bookmark to Pinboard is accomplished by a Python script implementing the Python-Pinboard library. To use the script, the Python can be installed by using the Easy Install method I wrote about earlier.


If you plan to install a lot of libraries from GitHub, it’s worth it to install the pip library. This can be done by executing the following:

easy_install pip

Now you can use pip to install directly from GitHub with the following command:

pip install -e git://

Pip is really a replacement for easy_install so once it’s installed, you can use it as a complete replacement for easy_install.

The Python Script

The Python script does several key things. The first is to read in all of the variables created by Keyboard Maestro. Next, the script uses the url on the clipboard to grab the page title. This is crucial since Pinboard requires two pieces of information to make a new bookmark, the url and the page title. I needed to add a bit of a bug fix after trying to bookmark one of Brett Terpstra’s pages that had a non-ascii character in the title. Python was throwing a unicode conversion error without the string encode function.

Finally, the script attempts to post a bookmark to The output from the Python script is stored in a new variable that is used for reporting back the outcome.


The first lines in the Python script after the import statements grab all of the system variables generated by Keyboard Maestro. The addition of variables in KM5 is convenient way to pipe information in and out of shell scripts. All variables in KM5 are accessible through a reference to the system variable$KMVAR_ where spaces are replaced by underscores. The are two significant limitations to these variables.

  1. They are read-only.2 Their values can not be changed by the shell script.
  2. Password-type variables can not be accessed by scripts.

Even with these limitations, there are exciting new possibilities for variables in KM5. The Pinboard macro only shows a small sampling of possible uses. Here are some the ways I use variables in this macro.

  • I use KM variables to hold the login account and password for my Pinboard account.
  • KM sets a variable to the contents of the clipboard for use in the Python script.
  • The output from the Python script is stored in a variable.
  • The Growl and Alert boxes use Tokens for the variables to display information about the state of the macro. For example this line: [cci]Pinboard Post for %Variable%postStatus% Complete[/cci] displays the Growl message with the title of the bookmark that was added to Pinboard.


The final steps of the macro are simply to notify the user as to whether the bookmark posting was successful. A successful post is followed by a Growl notification. A failure is shown in a persistent alert window. I chose this option so that I could troubleshoot the issue without the error message disappearing.


I’m still considering adding a couple of steps to the macro that writes the URL and outcome to a log file. It would be a nice record of how the macro performs and provide a quick text file of newly added Pinboard bookmarks.


During the development of this macro I contacted Keyboard Maestro support (Stairways Software) by email with a couple of questions about the new functionality. I received detailed responses within a few hours from the founder Peter Lewis. Their support is simply fantastic. The documentation can be a little sparse but I found that their support easily fills in the gaps. It’s that kind of support that makes me excited to continue making tools that depend on their application.

More to come on new KM5 macros…

  1. You can find the macro for download on GitHub

  2. AppleScript can change a variables value through scripting directly to the Keyboard Maestro Engine.