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.
Password, Permanent variables • Available to macros but not displayed.
• Not directly accessible via AppleScript.
Displayed in password fields in Prompt For User Input actions.
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.
Dictionary, Permanent, global in scope. • Available Almost Everywhere, including Scripts, but not Preferences.
• Dictionaries consist of the Dictionary Name, One or more pairs of Key Name, and Value
• Although Dictionaries are like Variables, they are kept in a separate category called Dictionaries.

Macros can create or read existing variables, which persist and are permanently stored (except Local and Instance variables which are transient).

Variables contain only plain un-styled text and 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. Variable may be used in Calculations if they contain a valid number or expression.

Kinds of Variable

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).

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.

Instance Variables (v8+)

Variables with names that start with “Instance” (trailing space not necessary) are considered private 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” (trailing space not necessary) are considered local to a specific execution 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

Setting Variables

Variables are usually created and set by Macro Actions, but can also be set by scripts. The Action that sets a variable will create it if need be. Variables do not need to be declared in any way.

The most direction Action to set a variable is the Set Variable to Text action.

This action processes the tokens and backslashed characters in the text and sets the variable. As will all text fields, if you wish to use another variable in the text you must use the %Variable% token, eg The value is %Variable%VarName%.

You can also use the Set_Variable_to_Calculation action. This action evaluates the numeric expression and then sets the variable to the result. As with all numeric fields, if you wish to use another variable in the calculation, you use the variable unadorned, eg VarName * 3.

There are many other actions that set variables.

Using Variables

There are many Macro Actions that can use variables. Some of these explicitly provide for entry of the variable name, but most provide for a more general text entry that accepts either token text or a numeric expression.
When editing a field:

  • Fields that expect text tokens show a small V.
  • Fields that expect calculations show a small C.
  • Fields that expect just a variable name show a small V.

Variables in Text Fields

Variables can be used in text fields using the %Variable% token. The %Variable%<VariableName>% token allows you to include a variable in the text, where <VariableName> is the name of the variable, and this is replaced by the value of the variable.

For Example, using the Insert Text Action:

You can also use a short form of just %Variable Name% to include variables as long as the variable exists and has a value and there is no corresponding text token, although generally it is better and clearer to use the longer form %Variable%Variable Name%.

Variable Arrays

While technically all Variables are just strings, you can access a variable as if it were an array (v7.2+) by setting the Variable to a delimited list of text, and then using the following notation:



  • <VariableName>” is any valid Keyboard Maestro Variable with a delimited set of values.
    • By default the comma , is the delimiter (see below for setting a custom delimiter).
  • <IndexNumber>” is an integer indicating the index (starting with 1) of the array value within the Variable Array.
    • This index can be determined using any Calculation, including simply a Variable Name, like i.
    • Examples:
      • %Variable%myList[i]%
      • %Variable%myList[3 * i + 2]%

How to Use Custom Array Delimiter

Place the custom delimiter after the closing bracket ].

  • For Example: %Variable%myList1[i]:%, where the colon : is the delimiter used in the Variable Array.
  • Of course, the Variable Array, myList1 in this case, must use the same custom delimiter.

Simple Example of Variable Array

Example of Variable Array Using a Variable for the Index

For a real-world example, see this Forum post: Combine Two Lists Using KM Variable Array

Variables in Calculation Fields

Variables can be used in calculations if their value holds a number or a numeric expression that can be evaluated. Variables are used unadorned in calculations, for example My Variable * 7.
You can also access variables in a token field numerically using the %Calculate% token. It is important to note that calculations can contain only numeric values. When you use the %Calculate% token to reference a variable or variable array element, it will convert the element to a number.

Variable Dot Notation

In a Calculation field you can reference the numbers in a variable (which is always a string) using dot notation:

Variable.x x coordinate
Variable.y y coordinate
Variable.left the left coordinate of a rectangle the top coordinate of a rectangle
Variable.right the right coordinate of a rectangle
Variable.bottom the right coordinate of a rectangle
Variable.width the width of a rectangle or size
Variable.height the height of a rectangle or size
Variable.fuzz the fuzz of an image match (rectangle,fuzz)
Variable.MidX the horizontal middle of a rectangle
Variable.MidY the vertical middle of a rectangle

The Variable Name and Dot reference are case insensitive.

Using Variables in Scripts

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 get and set Keyboard Maestro Variables in these types of scripts:

And you can generally access Keyboard Maestro variables anywhere else via AppleScript from whatever language you want to use.

Deleting Variables

  • Global Variables, including Password Variables, continue to exist (remained stored) until their value is set to "", the empty string.
    • Setting a Variable to %Delete% does not technically delete it. It continues to exist. It is just hidden from view in all of the Variable lists and in the Preferences.
    • However, a Variable set to %Delete% will behave as if it does not exist in most Actions, like a If Then Else Action using a Variable Condition comparing to exists.
  • Dictionaries continue to exist as long as there is at least one Key that has a value that is not "".
  • Dictionary Keys continue to exist until their value is set to "".

It may be a good idea to set a Variable to "" do if you no longer need it, or if it contains sensitive information (like a password) or a large value (like a file or web page contents).

Perhaps the best way to avoid variable clutter and eliminate sensitive and/or large values is to use either Local or Instance Variables when you do not need the Variable after completion of the Macro in which the Variable is used.

Inserting 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 just 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 in the Preferences Window

Variables are created on demand, but you can add, delete, see or change global variables in the Variables preference pane.

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

manual/Variables.txt · Last modified: 2017/11/16 20:08 by JMichaelTX