Is this a complete list of the KM Engine's scriptable functions?

It started to dawn on me today that BOTH the KM Editor and the KM Engine are AppleScript compatible. While I'm not too interested in manipulating the KM Editor, I am interested in getting information out of the KM Engine. So I started to compile a list of things that can be done with it. But I'm not sure if I have a complete list.

I did read pages like the following:

The above link is for a page stating that the KM Editors is OSA-scriptable, but doesn't mention the KM Engine, even though it gives examples for the Engine


And I tried to make a list of things that will work with the Engine. Here's my list:

  1. play sound alias "Harddisk:System:Library:Sounds:Glass.aiff"
  2. set n to calculate "JULIANDATE()"
  3. set clip to process tokens "%PastClipboard%3%"
  4. reload
  5. delete variable "My Result"
  6. (reading or writing global or local/instance variables, long list of options here)
  7. do script "macrotextname"/macrovariablename
  8. set bounds of window "name" to {a,b,c,d}

Is this a complete list? What I'm interested in doing is getting a list of macro names (or UUIDs) from the Engine for all the running macros. But since I couldn't find an example of this, I'm guessing I can't get that information.

You can open its AppleScript dictionary (Script Editor β†’ File β†’ Open Dictionary β†’ select Keyboard Maestro Engine) to see the full list of scriptable actions in the engine. There's a lot more in there, including an executing boolean property. But that's all it is, a TRUE/FALSE value for whether or not any macro is executing.

In addition to that, you can use commands to get a list of macros, hot keys, look at dictionaries and keys, process tokens, and more. Much more than I know what to do with given my limited AS skills :).

I don't, however, see any way to get a list of all executing macros from the engine's AppleScript (perhaps someone better than AppleScript at I can do so?). I asked ChatGPT about it, and it suggests using a macro in KM itself that launches whenever a macro launches and saves the name of the executing macro in a variable, which you could then check via AppleScript. However, there's no way to do that I'm aware ofβ€”the trigger it suggested doesn't exist :).

The alternative would be to add two commands to every single macro you wanted to track: One at the beginning appends the executing macro's name to a global variable. One at the end deletes the macro's name from that variable.

You could then use AppleScript to read the value of that variable. But that seems like a ton of work.


Through the .doScript method, everything.

I presume "do script" is referring to KM macros. In that case, it's useless for me, as I'm unaware of any KM actions that can tell me about the KM Engine, such as, in my example, the names or UUIDs of the macros that are running.

I never knew that. Thanks. I was only familiar with File / Open, not File / Open Dictionary.

I have used some of those properties, just by reading the KM documentation, not by reading them from the Script Editor.

Some of them have a little information that might help me. I will try them out. For example, gethotkeys and getmacros tell me about the Engine's known hot keys and macros, but probably not the ones that are running.

Exactly - I use get macros in MacroBackerUpper as part of getting a list of macros, groups, and IDs, but it has no data at all about running or not. It appears from my inspection β€” granted, an AS rookie's inspection β€” that the only thing related to whether macros are running or not is that true/false flag that indicates something is running or nothing is running.


Well, that flag could allow us to "poll" the engine and (inaccurately) estimate the Engine's Idle time, much like IDLE() reports the GUI's Idle time. So it's something.

Actually, if you know your macros always take over 1 second, then it wouldn't be an inaccurate estimate if you poll the Engine once per second. Also, if you end all your macros with the action "Pause 1.0 seconds" then that also would allow accurate polling of the Engine's Idle time.

The Engine's available macros -- keep that in mind if you have a lot of "contextual" macros, like ones that are only active when Safari is frontmost.

It might help if you maintain a separation between "macros" in the Editor and "executing instances" in the Engine. In KM you can get the currently-executing instances' UUIDs and work back from those to the name of the "parent" macros. And if you can do that in KM you can do it in AppleScript -- check the process tokens entry in the Engine's AS dictionary.

executing tells you if an instance of any macro is executing. If you want to get a list:

tell application "Keyboard Maestro Engine"
	set AppleScript's text item delimiters to ":"
	set theList to every text item of (process tokens "%ExecutingInstances%")
	return theList
end tell

..and so on.

Whether it's easier to do this in AS rather than with a KM macro is another matter! I'd probably stick to KM for most of it...

1 Like

Here's a thought: under the menu bar KM status is a "cancel" item that lists all the currently running macros. Maybe you can use that somehow?

I never knew the KM Engine could evaluate tokens when called by AppleScript. But now that I've just re-read the KM Engine dictionary, I see it in there. Thanks.

Now this token returns UUIDs, which is to be expected. I'm thinking that it might be better (at least for my use cases) to convert this to a macro name. And I see that there's a token for converting a UUID to a macro name. I think I can imagine how to use AppleScript to pass tokens with arguments to the KM Engine. (Just a little string manipulation in AppleScript or in KM.) Thanks.

Do consider whether this is worth doing. It's fun, for sure, and it'll be a learning experience. But you can do the same thing in a KM macro -- and that'll be quicker to write/edit/debug, has all the token/text manipulation you know and love, won't have the overhead of all those multiple inter-process communications, etc, etc.

And you can call that macro via AS or the new command line hook to run it from "outside".

You are right. This is the second time today I was a moron. I was so fixated on getting new information from the KM Engine, I didn't think of that point. You saved me some work. Thanks.

If you use Alfred, you can use the "Open with" action to open Keyboard Maestro with Script Script Editor will open the Engine's dictionary.

That's a very quick way of revealing an application's Applescript dictionary if one is a habitual user of Alfred's Universal Actions. Trying to do something similar just using the Finder does not work.

1 Like

or with Keyboard Maestro:

Works with Script Debugger, too.

Good news: you can also use Keyboard Maestro to open an application's dictionary in Script Editor.

For example, you can use an Open a File Folder or Application action.

For another example: one could use an Open the Finder Selection action.

And since we're talking AppleScript, don't forget:

tell application "Script Editor"
	open (path to application "Keyboard Maestro Engine")
end tell

(Or tell Script Debugger, if that's your preference.)

If you want to use the command line, watch out for the "real" location of your apps:

open -a /System/Applications/Utilities/Script\ /Applications/Keyboard\