Adding Keyboard Maestro Macros to Quick Actions in Finder

A few weeks ago, Bob Cassidy taught us some tips about how to get Keyboard Maestro to do our bidding. He was helping me with a specific macro that needed to be triggered on a Finder item. At the end of his explanation, he wrote:

I think the ideal way to trigger this macro would be by right-clicking on the file and choosing from the contextual menu. In the back of my mind, I thought that Keyboard Maestro had that function, but after investigation, I don’t see a way to do it. If anyone knows how to do that, I would appreciate knowing how.

I went on my own quest to figure out how to do it. I got really close to solving the problem, and then Bob came at it from a slightly different angle and we converged on the solution.

I’ll start with the path I went down and then we’ll veer into Bob’s method to take us over the finish line. If you’d like to fast-forward a bit (or read ahead if you’re on the blog), I’ve written out the steps in an easy-to-read list at the end. But what’s the fun in that? Let’s go the long way around to get to the solution.

So we’ve got a Keyboard Maestro macro that acts on a file or folder in the Finder. My particular macro acts on PNGs in the Finder. Instead of remembering a keystroke, or having to go up to the Keyboard Maestro Context Menu in the menu bar, we want to just right-click on the file, and choose the macro from the Quick Action menu.

Before we get into the solution, I want to warn you that Apple uses a lot of different names for Quick Actions and it may get pretty confusing. I will try to add to the confusion by pointing out all of the names each time they change.

Export Macro as a Finder Quick Action

Inside Keyboard Maestro, if you select a Finder macro, you can select File → Export, and one of the options is Export as Finder Quick Action. That sounds like exactly what we want. By the way, there’s an export menu available by right-clicking on a macro, but oddly that export menu does not include the Export as Finder Quick Action option; you have to do it from the File menu.

The Keyboard Maestro export option calls it a Quick Action, but you are immediately asked what you want to name the saved Service.

Once you have the Service saved, you still have to add it to the Quick Action menu. You’ll get a popup that explains that to enable this Finder Quick Action, you need to select customize from the Quick Action menu. To do this, we need to right-click on a file in the Finder, and in the menu that pops up, choose Quick Action. You’ll see a list of your existing Quick Actions, and at the bottom of the list it says “Customize”.

This customize request launches System Settings (or System Preferences if you’re pre-Ventura), to Privacy & Security → Extensions. Wait, are they Services? Quick Actions? or are they Extensions??? Within the Extensions menu you’ll see Actions (but they’re not quick). Ignore those and go to the bottom of the list and choose Finder. Within Finder we get a section that says “Select Quick Actions to show in Finder:” at the top. In this list you can finally see the Quick Actions you already have installed. You’ll also see the one you exported from Keyboard Maestro. Check the box next to your Finder macro/Quick Action/Service/Extension’s name.

Now from the Finder, if you right-click on a file and choose Quick Action from the menu, you can choose your Keyboard Maestro macro. Whew!

If this is the first time you’ve added a Keyboard Maestro macro to the Quick Action menu, you’ll be asked to grant the Finder permission to control Keyboard Maestro.

I’m really glad that apps can’t just suddenly start running Keyboard Maestro macros without me knowing about it!

Once I had my macro in the Quick Action menu and I’d granted Finder permission to run it, I figured I was golden. I right-clicked on a PNG and chose my macro from the Services/Quick Action menu, and I was greeted with an error:

The action “Run AppleScript” encountered an error: “Keyboard Maestro Engine got an error: do script found no macros with a matching name (macros must be enabled, and in macro groups that are enabled and currently active).”

I knew that the macros were enabled and they were in groups that were enabled but I didn’t know what “active” meant. When I first wrote this up, the author of Keyboard Maestro, Peter Lewis, actually wrote a comment on the post and pointed me in the right direction to solve the error.

Before we get into that part of “today I learned”, what’s this about AppleScript? I never wrote any AppleScript! At the bottom of that error window, it had the option to Show Workflow, which opened Automator. I never created an Automator workflow … or did I?

Show Workflow opened the Services menu inside my user Library folder, with a workflow named after my Keyboard Maestro macro. So my macro is a service is an extension is a Quick Action is a workflow … got it.

Opening this Automator Workflow revealed an AppleScript that was trying to run my Keyboard Maestro macro. I found it ironic that Keyboard Maestro created an AppleScript. I’ve been trying to use Keyboard Maestro rather than learn AppleScript because I’ve been worried AppleScript might go away sometime soon as Apple seem to have lost interest. And yet here Keyboard Maestro goes creating an AppleScript for me!

Since I haven’t learned AppleScript, I didn’t know why the Workflow/AppleScript/Service/QuickAction was failing. I sent Bob everything I did to get to this point and asked him if he knew what was wrong.

on run {input, parameters} 
    set r to ""
    set c to 0
    repeat with theItem in input 
        set p to POSIX path of theItem 
        if c = 1 
            then set r to r & {ASCII character 10} 
        end if 
        set r to r & p 
        if c > 0 
            then set r to r & {ASCII character 10} 
        end if 
        set c to c + 1 
    end repeat 

    tell application "Keyboard Maestro Engine" 
        do script "13D4FF48-A5C9-4DA9-9AF5-7BD772124502" with parameter r 
    end tell 
    return input 
end run

As it turns out, nothing was wrong with the AppleScript. Keyboard Maestro’s developer Peter suggested I open the macro in question and run the Interactive Help option under the Help menu. Learning about this the Interactive Help made me happy I had a problem with the macro because it’s crazy cool.

With the macro that’s giving you trouble selected, Interactive Help asks you what’s wrong. The two most interesting choices are “Something unexpected is happening” and “Something expected is not happening.” I chose the second option and it went through a series of tests on the macro. For the tests that succeed, you get a happy check, but for the ones that fail, you get a sad red x which then takes you to another step to diagnose the problem.

When I ran it on my macro, it failed one of the tests and pointed me to this “active” thing. At the top of a macro, you define the triggers to make it go. What I didn’t realize is that these triggers aren’t options, they are required to make the macro active. When I originally created the macro (with Bob’s guidance), I had the trigger set to “The status menu is selected”. But if I’m calling the macro using a Quick Action, then the status menu is not selected so the Quick Action simply cannot run.

As I explain it, this sure seems obvious, but I really hadn’t given that much thought to the importance of the triggers until the Interactive Help menu guided me to it!

Once I fixed the trigger to make the action active for Quick Action to be allowed to run, it worked!

Bob’s Solution

Before I received help from Peter on this, I sent Bob everything I did up to and including the error about the macro being active. I’m not sure if he saw what I sent, but he came at this from a different angle and he arrived at essentially the same spot but with a solution that was a bit more simple.

The one interesting bit in the auto-generated AppleScript code that I was using was towards the end. It says:

tell application "Keyboard Maestro Engine"
    do script "big long ASCII set of characters" with parameter r
end tell

This part of the script actually made sense. It’s telling AppleScript to tell Keyboard Maestro to run my script. I even knew what that big log ASCII set of characters was. I don’t know if you remember, but last week I told you about Dan Thomas’s awesome Keyboard Maestro macro that lets you do version control on your macros. I explained that the exported macros have your human-readable name, but then they’re followed by a big long ASCII set of characters that are the UUID for the macro from Keyboard Maestro. I know that’s a lot of info I’m asking you to keep track of in your head, but I was pretty sure that UUID is the only way you can address the macro from within AppleScript.

What I didn’t understand though was what “parameter r” was. Peter (in his comment on the blog post) explained:

The “with parameter” value is placed in the %TriggerValue% token when the macro is executed – that is how the file you have selected in the Finder is passed to the macro.

And one more thing from Peter. He explained that the UUID could be replaced by the macro’s name, so you could write it as do script "Macro Name". That’s pretty cool.

Bob’s Path to Success

Now let’s switch gears to Bob’s method.

Bob’s solution was to fire up Automator, add a “Run AppleScript” action and type in the very simple lines that were in the auto-generated script, with the tell Application Keyboard Maestro and do script blah blah blah. His script worked as well.

But I had a question. The auto-generated AppleScript knew which UUID called the right script only because I had exported from the macro I wanted to run. How did Bob know the UUID of the macro if he didn’t go through the export step? I knew it was a UUID because of the version control macro from Dan Thomas, but in Bob’s explanation he referred to it as a “macro script ID number designation thingy”.

Bob’s explanation of how he knew the UUID taught me a new trick that makes this roundabout explanation worth all the time it’s taken to explain. Remember that I’ve not paid much attention to the trigger part of using Keyboard Maestro macros?

One of the reasons I’ve not dug into triggers too far is because there are SO many options on how to trigger them. You can use a hotkey, you can have it run when a USB device is plugged in, you can have it trigger when your audio output changes or when a volume has mounted – the list goes on and on. Bob explained that one of the many options is to trigger macros via a script. If you choose the script option, you can select AppleScript.

This automatically creates an AppleScript for you that says to tell application Keyboard Maestro Engine to do script and shows you the UUID (also known as the “macro script ID number designation thingy”.) This is exactly the AppleScript that you can export as a Quick Action as I described earlier.

Bob doesn’t use the script itself, but he does use that script to find the UUID, and then put it in a very simple script:

tell application "Keyboard Maestro Engine"
    do script "Your UUID Goes Here"
end tell

Concise Steps to Success

I walked you down these two different paths, again to demonstrate how much I’m learning by working on silly scripts like checking the Alpha checkbox in the Save As dialog box for Preview. I learned from Bob and now I learned from the developer himself, how cool is that?

The only problem with my storytelling is that you don’t have a concise, step-by-step process to turn a Keyboard Maestro macro into a Quick Action, so let me boil it down for you here at the end.

1. Write the Keyboard Maestro macro that works on a Finder item
2. Set a trigger that you know will be active
3. With the macro selected, select File → Export → Export as Finder Quick Action
4. Open System Settings (or System Preferences) and navigate to Privacy & Security → Extensions → Finder → and tick the checkbox next to your newly created Quick Action
5. Save your Service in Automator
6. To test, right-click on an appropriate file in the Finder and choose Quick Actions and select your macro/Quick Action
7. If Finder asks for permission to run Keyboard Maestro, say yes
8. If anything goes wrong, check out the fabulous Interactive Help in Keyboard Maestro’s Help menu.

I promise not to talk about Keyboard Maestro every week but I was so excited to learn even more about this amazing automation tool that I felt compelled to share. Also, if I write about it, I can always find the solution online when I forget how to do this!