Development,  Tech Tips

Keyboard Maestro URL Handler – Link Injection


This post outlines some advanced usage of the Keyboard Maestro URL handler (KMLink).

A few weeks ago I was automating some Chrome form filling with Keyboard Maestro. It occurred to me that the perfect trigger for what I was doing would actually be a simple link within the Chrome webpage itself (or a simple bookmarklet); when the link/bookmarklet is clicked, the KM macro is executed. How about a little backstory before I get to the “here’s how to do it!” ?

We use a project management system called ActiveCollab. It’s a great piece of web-based software, but often simple things take several steps. When I want to quickly mark a task as “Due in 2 business days” (which I need to do very often) it’d be whole lot nicer to click a link to set this, than to have to go to the edit screen, pull up the date picker, think about what two business days from today is, click that date and submit the form. Sure, I could write a module for Active Collab that would do what I want, but Keyboard Maestro provides me with much more freedom and I can build it in minutes instead of hours.

Three Components

Component 1 – URL Handler: If you haven’t been here already, you must read Keyboard Maestro URL handler (KMLink) before continuing.

Component 2 – Macros: I already had written several macros to interact with ActiveCollab. These worked, but I wanted to trigger them via a link on the page (or a bookmarklet).

Component 3 – Links: The last piece was to get the links (that trigger the macros) onto the ActiveCollab pages. I knew I could achieve this with a userscript (I’ll let you look into this).

Result & Demonstration

The result is that I can use userscripts to inject custom links into pages that trigger Keyboard Maestro macros. It works, and it works well! Here’s what the injected links look like:

Result - the highlighted links all trigger KM macros! They are added to any Task page.
Result – the highlighted links all trigger KM macros. They are added to all Task pages of the site.

Get Started

Step 1: By now you should’ve already read through Keyboard Maestro URL handler (KMLink). Step 1 is to make sure you have setup and your URL handler is working correctly.

Step 2: Build a test macro. I suggest something very simple; maybe just use a single “Alert” action that says, “Hello, world!”

You will probably have to start your 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.

Step 3: Copy the UID of the Macro. You’ll find this by viewing the macro in Keyboard Maestro and going to Edit » Copy As » Copy UID.

Step 4: Create a link on a webpage. Here’s an example:

To make sure the link doesn’t trigger a page change, I use an href of “#” with an onlick property that actually triggers the url.

E90A25BD-5ADD-46A5-B07A-9505EBF1158C is the macro’s UID. We use the UID because it doesn’t change if you rename your macro.

You should add links to webpages however you see fit. If you control the site contents you can add the link as you normally would (wysiwyg, code, etc.).

If you don’t have access to alter the site, you may consider using a userscript to inject the link into the page. I manage userscripts in Chrome using the TamperMonkey extension. Here’s the userscript I use for my ActiveCollab integration. Note that it isn’t exactly a simple example due to how pages load in ActiveCollab, but it should give you some ideas.

 Step 5: Try it out. When you click the link, the macro should execute, and you should see the alert. If it doesn’t work, make sure everything is as basic as possible. Make sure that you already executed the to register the URL handler. You may need to restart your browser. You may need to authorize Chrome to use the handler (if prompted to do so).


This has significantly changed how I work. The macros take the guesswork out of day-to-day operations, and being able to click a link to fire them off is great. I hope this post got you thinking about the possibilities offered by a Web Browser + Keyboard Maestro combination.

Leave a Reply

Your email address will not be published.