Keyboard Maestro 5 IconKeyboard Maestro 5

Conduct your Mac Like a Pro!

Scripting

Controlling Keyboard Maestro via Scripting

The primary scripting interface to Keyboard Maestro is the Keyboard Maestro Engine’s do script support. You can ask Keyboard Maestro to:

Note in most cases you must ask “Keyboard Maestro Engine”, not “Keyboard Maestro”.

The easiest way is to use the name, for example:

tell application "Keyboard Maestro Engine"
  do script "Name of Your Macro"
end tell

The macro must be defined and enabled, and the macro group must be enabled and currently active.

If there is more than one macro with the same name, you will get an error, so you can use a UID instead of a name.

tell application "Keyboard Maestro Engine"
  do script "D0C150C7-8A0C-4837-918A-427E2BCFB6B9"
end tell

The do script will not return until the macro is finished executing.

You can determine a macro’s UID by selecting it and choosing Copy UID command in the Edit menu.

An even more powerful way to script Keyboard Maestro is to execute specific actions based on their XML code. This allows you to construct any action, including changing the action on the fly, without having to create a macro first. A simple example would be:

tell application "Keyboard Maestro Engine"
  do script "<dict><key>MacroActionType</key><string>SwitchToLastApplication</string></dict>"
end tell

The easiest way to determine the appropriate XML is to create an example action in an example macro and then export the macro.

You can disable or enable a Macro or Macro Group from AppleScript with:

tell application "Keyboard Maestro"
  setMacroEnable "Macro/Macro Group Group Name or UID" with/without enable
end tell

This actually asks the editor to disable or enable the macro or macro group, so the change is both visible and permanent.

Alternatively you can use the Set Macro Enable action.

You can start editing a Macro or Macro Group from AppleScript with:

tell application "Keyboard Maestro"
  editMacro "Macro/Macro Group Name or UID"
end tell

You can ask Keyboard Maestro Engine to reload the macros with:

tell application "Keyboard Maestro Engine"
  reload
end tell

Executing Scripts

You can execute shells scripts, AppleScripts, Automator Workflows, or filter the clipboard using BBEdit Text Factories.

AppleScripts and shell scripts give you a powerful way of adding new facilities we have not specifically provided for, as well as controlling other applications.

The results of AppleScripts and shell scripts can be displayed, or they can be typed or pasted in to the current selection, or saved into a variable. This allows you to insert text that depends on many factors, such as date calculations, file listings, SQL queries, web pages, or anything else you can imagine.

You can also use the clipboard to pass data between actions. For example, a script can use pbpaste to read the current clipboard, and pbcopy to set the current clipboard. You can use the Delete Current Clipboard action to restore the clipboard afterwards.

Shell scripts can access variables as environment variables with names like $KMVAR_Variable_Name (KMVAR_ is prefixed, and spaces are converted to underscores).

AppleScript can read or write variables with:

tell application "Keyboard Maestro Engine"
  set kmVarRef to make variable with properties {name:"Calculation Result"}
  set oldValue to value of kmVarRef
  set value of kmVarRef to 10
end tell

You can delete a variable with:

tell application "Keyboard Maestro Engine"
  delete variable "Calculation Result"
end tell

AppleScripts are executed in the background via osascript. This means they are not allowed to do user interaction. You can work around this by asking an application like System Events to do the user interaction for you, for example:

tell application "System Events"
  activate
  display dialog "Hello"
end tell

The osascript tool will execute in 64-bit mode if available, which may be a problem if you have old versions of AppleScript extensions installed. However, you can set the command line tool that is used to execute AppleScripts as described in Other Hidden Preferences.

See also the Variables section.

Enhancing AppleScript

Keyboard Maestro Engine makes several of its facilities available to AppleScript.

You can ask it to play a sound with:

tell application "Keyboard Maestro Engine"
  play sound alias "Harddisk:System:Library:Sounds:Glass.aiff" 
end tell

You can ask Keyboard Maestro Engine to perform a calculation for you with:

tell application "Keyboard Maestro Engine"
  set n to calculate "JULIANDATE()"
end tell

You can ask Keyboard Maestro Engine to process tokens for you with:

tell application "Keyboard Maestro Engine"
  set clip to process tokens "%PastClipboard%3%"
end tell

See also the Calculations and Text Tokens sections.

Continue on to Windows

Close

Feedback Form

Please provide any feedback you may have


Email Address:
Subject:
Feedback:


Your email address is appreciated but is not required and will not be saved.
It will be used only for responding to or clarifying this feedback.

Documentation

Old Documentation