User Tools

Site Tools



Keyboard Maestro includes variables with three different scopes of allowed access, in order of scope, with broadest scope first:

Scope Availability
Global, Permanent variables • Available Everywhere, including Scripts and Preferences.
Instance Variables (v8+) • Restricted to a specific execution sequence.
• Available to Macro where it was created, AND Sub-Macros in that Macro, but for a given execution instance.
• So these Variables are private to each execution of the same Macro, even when running simultaneously.
• Available to Prompt For User Input
Not Available to scripts, Preferences, HTML Prompt
Local Variables (v8+) • Restricted to Macro where it was created
• Available to Prompt For User Input
Not Available anywhere else, including Sub-Macros.

All of these may be used in any text field in an action, as well as in Calculations in a numerical field, or within the in Calculate Token. Obviously, the Variable must contain only a number to be used in Calculations.

For more info about each of these Variable types, see below.

Global Variables

Global Variables are permanently stored on your Mac drive (like a file), and are available for read/write in any Macro or Action, not just the Macro where the Variable was created. These variables persist between logins and restarts of your Mac.

Variable names must start with a letter, and then can contain letters, numbers, spaces, or underscores. Variable names are case insensitive, but their case is remembered. Variable names should not include a function or operator name with spaces around it (eg “ MOD ” , so “A MOD B” would not be a valid variable, although “MODULE” would be fine).

Instance Variables (v8+)

Variables with names that start with “Instance ” or a TBD character (FIXME) are considered local to a specific execution sequence. Each time the macro is run, they will start empty but their value can be seen and changed by other macros within the same execution sequence (for example, if you execute a macro using the Execute Macro action, that macro can see and change the instance variable). Since two instances of a macro can be running at the same time, this is useful to ensure they each have their own version of the variable.

Since Local and Instance variables are transient, they are not shown in the Variables preferences pane.

Local Variables (v8+)

Variables with names that start with “Local ” or a TBD character (FIXME) are considered local to a specific instance of a specific macro. Each time the macro is run, they will start empty and no other macro will see or be able to change values.

For a good discussion on the new Version 8 Local and Instance Variables, see this Forum topic:
KM8: Local and Instance Variables

Password Variables

Variables with names that start or end with “Password” or “PW” are considered passwords – their values will not be stored (except in memory) and they cannot be read directly by shell scripts or AppleScripts, though their consequences can easily be extracted, eg with the Set Clipboard to Text action, so you should clear them as soon as they have served their purpose. The Prompt For User Input dialog will display such variables in a password field.

Accessing Variables Like an Array

Variable values are text, but they can contain comma separated numbers, and can then be accessed as arrays (eg Variable Name[1]). Mouse positions, window frames and the like can then be stored and manipulated in variables, and you can access the fields with “struct” like forms like Variable Name.width (field names include: x, y, left, right, top, bottom, width, height, midx, midy, and fuzz).


Variables values can be accessed from scripts you execute with Keyboard Maestro via environment variables, and from AppleScript using AppleScript commands to the Keyboard Maestro Engine, and from web browser JavaScript you execute with Keyboard Maestro via the document.kmvar dictionary, see the Scripting section for more details.


You can also set a variable value to %Delete% to avoid having it show up in variable popup menus. This is also a good idea to do after a variable has contained sensitive information (like a password) or a large value (like a file or web page contents).

How To Insert In Actions

You can add a variable to an action using the Insert Variable menu in the Edit menu or Variable menu in the Insert Function sub-menu in the Edit menu or Variable menu in the Insert Token sub-menu in the Edit menu, or by selecting from the popup menu next to some variable fields.

Fields that expect a variable show a small V in the field while editing it, and you can use Type Completion to complete variable names in such fields.

Accessing All Global Variables in Preferences Window

Variables are created on demand, but you can add, delete, see or change variables in the Variables preference pane, and you can read and write variables from AppleScript, see the Scripting section.

Local and Instance Variables are not accessible from either the Preferences Window or from Scripting.

manual/Variables.txt · Last modified: 2017/09/25 14:00 by JMichaelTX