User Tools

Site Tools


manual:Plug_In_Actions

**This is an old revision of the document!**

Plug In Actions

You can develop custom Macro Actions using a facility known as Plug In Actions (PIA). After you install a Plug In Action in your local Keyboard Maestro Support folder, you can use them like the built-in Actions.

Third Party PIAs

You can download PIAs developed by others from these sources:

How to Install

PIA Install Files are .zip Archive Files

  1. Initial Install: Drop on the Keyboard Maestro app Dock icon
    • This will create a PIA sub-folder by the same name as the .zip file
    • Do not unzip the file
  2. To Update An Existing PIA
    1. First Manually Delete or Move the PIA Sub-Folder from:
      ~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Actions/ folder
    2. Then Drop the .zip file onto the Dock Icon

Building a PIA

PIA Folder

A Plug In Action is Contained in a Folder,
Whose Name:

  1. Should generally closely match the action name
  2. Must be made up of only ASCII alphanumerics, underscores and spaces.
  3. Must be unique among all plug in actions.
  4. Is stored in the Keyboard Maestro Macros.plist to reference the plugin action.

The PIA folder contains a set of files, including:

  1. Keyboard Maestro Action.plist – an XML file describing the action.
  2. A script file
    • whose name must be made up of only ASCII alphanumerics or underscores, plus an ASCII alphanumeric extension.
    • It may be a shell script or an AppleScript.
    • If it is a shell script, it will be made executable automatically.
  3. Icon File: 64×64 png icon (optional).

The PIA Folder must be stored as a .zip archive file for installation.

PIA PList

The format of the Keyboard Maestro Action.plist is a Cocoa Property list containing a dictionary with the following keys and values:

Key Description
Name the name of the action (which appears in the Category/Actions list)
Script the name of the script, made up of only ASCII alphanumerics or underscores, plus an ASCII alphanumeric extension
Icon [optional] the name of the icon png file, made up of only ASCII alphanumerics or underscores plus .png
Title [optional] the title displayed on the action, which can include %Param%XYZ% tokens. It should usually not include other tokens. If it is missing, the Name will be used
Timeout [optional number] the default timeout in seconds. Set it to 0 if the action needs no timeout. The default is 99 hours
Author [optional] the author of this action
URL [optional] a URL for the author or this action
Help [optional] a short (Tool Tip) explanation of this action
Results [optional] what to do with the output of the script if any. Possible Values: None, Window, Briefly, Typing, Pasting, Variable, Clipboard – multiple values can be used, seperated by a bar (|), the first specified value is the default
Parameters [optional] an array of parameters to the script, each entry is a dictionary as described below

Plist Parameters

Each parameter in the Parameters array is a dictionary with the following keys:

Label the name of the parameter. The same rules as Keyboard Maestro Variable Names apply. The label is displayed to the user and used to pass the parameter to the script. Obviously, the label must be unique amongst all parameters
Type the type of the parameter. Possible Values: String (single line), TokenString, Calculation, Text (multi-line), TokenText, Checkbox (0 or 1), PopupMenu or Hidden. The Type specifies how the value is displayed to the user and what processing is applied before it is passed to the script. Hidden types are text token processed, but are not displayed in the editor
Default [optional] the default value when the action is created
Menu [required if Type is PopupMenu] the values of the popup menu, separated by |

Warning: Keys are case sensitive.

Retrieving Parameters in a Script

Parameters are passed to the script via environment variables with names starting with KMPARAM_ similar to how variables are passed to shell scripts with the Execute Script action. So a parameter named “My Text” would be in an environment variable KMPARAM_My_Text. You can access the envirnment variables from AppleScript with system attribute “KMPARAM_My_Text”. Note that AppleScript’s system attribute is not safe for international characters, although can use code like:

set myText to do shell script "echo $KMPARAM_My_Text"

In normal use, once a plug in action is read, it will stay in memory and changes will not be noticed (although the script will be executed each time, so changes to that will be noticed). To cause the editor and/or engine to notice changes to the plug while in development, use AppleScript to reload the macros:

tell application "Keyboard Maestro" to reload
tell application "Keyboard Maestro Engine" to reload

PIA Failure

If the Plug In script fails, the action will fail (v9.0+), potentially aborting the macro.

manual/Plug_In_Actions.1622506438.txt.gz · Last modified: 2021/05/31 20:13 by JMichaelTX