KM8: Local and Instance Variables

Thanks, Peter.

What about the single character prefix that @Tom and I suggested:

I dislike verbose variable names. :wink:

1 Like

Yes, @peternlewis, if I look for example at the screenshots of my Retina Macros, which are exclusively using instance/local variables, honestly, I cannot say it is nice to have a five- or eight-letter prefix on each variable! It’s clunky.

So, this time, I completely agree with @JMichaelTX.

1 Like

I have not decided on a choice for them, nor weighed the consequences of such a choice. So no, there is currently no short form.

1 Like

This is resolved for the next version (after 8.0.2). Local and Instance variables will be in the environment variables.

Local Variables will work in Prompt For User Input and (non-asynchronous) Custom HTML Prompts.

1 Like

Fixed in Keyboard Maestro 8.0.2.
Please confirm and check “Solved” if fixed.

As of 8.0.3, local and instance variables should work in Prompt For User Input and Custom HTML Input windows.

Also, you can now access them from scripts by using the KMINSTANCE environment variable as a key to which set of variables.

set inst to system attribute "KMINSTANCE"
tell application "Keyboard Maestro Engine"
	set v to getvariable "LocalVar" instance inst
	setvariable "LocalOut" instance inst to "FromAS"
end tell

Wow! Many thanks for this, Peter. :+1:

This is huge.
I just confirmed it running Keyboard Maestro 8.0.3 (8.0.3) on macOS 10.11.6.
Also confirmed that running the same script outside of KM does NOT have access to the local/instance variable, which is proper.


Demo of Use of Local and Instance Variables

To improve my understanding of how these variable types work, I wrote the below macro. Hopefully it will help others as well.

Everything appears to work as advertised! :+1:

Please feel free to ask any questions about this.

Example Output

Press OPT-KeyPad1 to Continue BOTH Instances

###MACRO:   Local & Instance Variable Test KM 8.0.3

~~~ VER: 1.0    2017-10-04 ~~~

Local & Instance Variable Test KM 8.0.3.kmmacros (15 KB)
Note: This Macro was uploaded in a DISABLED state. You must enable before it can be triggered.




  • Demo The Use of Local & Instance Variables
    • Shows that multiple simultaneous executions (instances) of a macro keep both private to that instance.
    • Changing a Variable in one instance does NOT affect the other instance
    • The script run by each instance also sees the proper variable values


  1. KM 8.0.3+
  2. macOS 10.11.6 (El Capitan)
  • KM 8 Requires Yosemite or later, so this macro will probably run on Yosemite, but I make no guarantees. :wink:

NOTICE: This macro/script is for TEST Purposes ONLY


  1. Trigger the macro to start the _first_instance
  2. Observe the variable values in each Display Window
  3. Trigger the macro again to start the second instance.
  4. Observe the variable values in each Display Window
  5. Press OPT-KeyPad1 to continue BOTH instances.
  6. Observe the Script popup Dialog for BOTH
  7. Click OK on BOTH dialogs
  8. Observe the Display Windows for BOTH instances.


  • Carefully review the Release Notes and the Macro Actions
    • Make sure you understand what the Macro will do.
    • You are responsible for running the Macro, not me. :wink:
  • Assign a Trigger to this maro. I prefer TBD.
  • Move this macro to a Macro Group that is only Active when you need this Macro.
  • ENABLE this Macro.

TAGS: @KM8 @LocalVar @InstanceVar @Script


This is great! Many thanks!


@peternlewis, thanks again for giving us local and instance variables. Very, very useful.

Feature Request

I know you're going to shoot me for asking this, but I need to ask:
Could you please provide a way of viewing local and instance variables while a macro is running?

One UI would be to allow them in the Pref > Variables panel.

Use Case: Would greatly aid in debugging a macro.
Without being able to see these variables as we step through the actions makes it very hard to identify the problem sometimes.
I'm sure you understand, since you have used many software debuggers over the years.

Actually it just hit me: Maybe a better UI would be to have a Variables panel in the KM Debugger, you know, like the Chrome JavaScript debugger:

Thanks for considering this request.

1 Like

For now, the best solution is probably to use the Log action and tail -f or Console to watch the Engine.log file.

What is the JXA equivalent for the above codes? Thank you.

I don’t know. Perhaps someone who is better versed at JXA can answer.

I finally worked it out:

JXA Script to Get/Set Local & Instance Variables

var app = Application.currentApplication()
app.includeStandardAdditions = true

var kmInst = app.systemAttribute("KMINSTANCE");
var kmeApp = Application("Keyboard Maestro Engine")

var myLocalVar = kmeApp.getvariable("Local__MyVar",  {instance: kmInst});
kmeApp.setvariable("Local__FromJXA", {instance: kmInst, to: "Set in JXA Script"})

Here's my simple test/demo macro:

###MACRO:   Get Local Variables in JXA Script

~~~ VER: 1.0    2017-10-11 ~~~

Get Local Variables in JXA Script.kmmacros (3.1 KB)
Note: This Macro was uploaded in a DISABLED state. You must enable before it can be triggered.


Great! It would take me forever to figure it out, which means I would not be able to. Thank you.

1 Like

Not as good as watching variables update live but:
Here's a macro to display all current Instance variables. Easily modifiable to also show Global variables. Can't show any local variables (even ones defined in the macro).

I use it as a subroutine and just call it as needed while debugging.

Thanks for sharing.

That is proper behavior for local variables.
However, we can access local variables from AppleScript.
But I don’t know how to get a list of local variables like I can with global variables:

set kmVarList to every variable whose name starts with kmPrefix

@peternlewis, any way to make this work for Local variables?

You could get them from the environment:

[test] Show Locals in Env.kmmacros (2.1 KB)

OK, thanks Tom. If we can get them from a shell script, then we should be able to get them from AppleScript. One issue with the shell script is that how can we tell if the underscores between words in the KM var name are actual, or just for the shell?

Good catch. Running this…

…I only get this:

That is: the first variable (the one without the underscores) is not in the environment. But it should be, I think.