Keyboard Maestro URL Handler (KMLink) – Introduction and Basic Usage

Keyboard Maestro offers many ways to trigger macros, but unfortunately there isn’t a URL handler that lets you trigger macros via a URL. There are a number of keyboardmaestro://  URLs handled by the built-in url scheme, but executing a macro isn’t an option. If you’re interested in triggering macros via bookmarklets and Finder shortcuts, read on…

I’ve written a URL handler that allows you to execute macros and pass variables to them. It’s a simple app that registers a URL handler to process kmlink:// links.

Installation

1. Download the KMLink-v2.app zip file
   1. v2 allows you to pass variables; v1 did not
2. Extract KMLink.app to your Applications folder
3. Open the application. You only have to open it once (which will register the handler), but you need to leave it on your system.

If you’re curious what the application does, I encourage you to (after downloading it and extracting the application) right-click on the application and select “Show Package Contents”. Browse to Contents » Resources » Scripts and open main.scpt in the Applescript Editor.

Usage

I’m going to walk you through a basic scenario. We want to visit a URL that will trigger a macro that shows an Alert containing the variable we appended to the URL.

Step 1: Create the macro

1. Open Keyboard Maestro and create a new macro (within a macro group that is “Available in all applications” and “Always activated”)
2. Set the macro title to  KMLink Demo
3. Do not set a trigger
4. Add a new “Alert” action
5. Add the following as the Alert’s comment:  %Variable%FirstName%

Step 2: Get the macro’s UID

We use the UID because it’s unchanging and safer than calling a macro via its title.

1. With the macro selected, click Edit » Copy As » Copy UID.

Step 3: Try the URL trigger

1. Visit the kmlink:// URL in your web browser. Replace the [UID-HERE] part with the UID you got in step 2:
   1. kmlink://com.apple.Applescript.KMLink?macro=[UID-HERE]
   2. If the alert popped up, KMLink.app is working correctly. You should see an alert without the variable showing.
   3. If the alert did not pop up, send a message to @agileadam and I’ll try to help.
2. If you realized the variable is missing from the alert, that’s excellent! We didn’t pass it along…
3. To add the variable (or any number of variables for that matter), you simply add them to the end of the URL as additional parameters. Please understand that the URL has to be valid (so spaces should be written as %20  for example).
4. Here are some examples:
   1. kmlink://com.apple.Applescript.KMLink?macro=[UID-HERE]&FirstName=Adam
   2. kmlink://com.apple.Applescript.KMLink?macro=[UID-HERE]&FullName=Adam%20Courtemanche
   3. kmlink://com.apple.Applescript.KMLink?macro=[UID-HERE]&FirstName=Adam&LastName=Courtemanche

Step 4: Make it easy to use

There are a number of ways to use this new URL trigger. Here are the most common:

Bookmarklet

Bookmarklets, for our purposes here, are just bookmarks that, when clicked, will trigger a macro.

1. Create a new bookmark. Set the URL to the URL you tested above.
2. Click the bookmark to run the macro. Done!

Finder shortcut

I’ve used these to trigger a macro via an icon in my dock. You can use them however you use other items in Finder. Click it to execute your macro.

1. The simplest way to do this is to create a bookmarklet (as explained above)
2. Drag the bookmarklet into a Finder folder (I usually just drag to my desktop).
3. Optionally change the icon of the shortcut. This is explained well at OS X Daily.

Inject links into a webpage

This is more complicated because it requires some basic coding knowledge and (possibly) and understanding of user scripts. I’ve written a full post about this, entitled Keyboard Maestro URL Handler (KMLink) – Link Injection.

Troubleshooting

After clicking a bookmarklet (or link), my chrome window is no longer active

You may have to start KMLink macros with an “Activate Google Chrome” (or Safari, or whatever you use) action. This makes sure that after opening KMLink it bounces back to your browser to carry out the macro’s actions.