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.
You can download PIAs developed by others from these sources:
PIA Install Files are
.zip Archive Files
.zipfile onto the Dock Icon
Plug In Actions are used just like the built-in Keyboard Maestro Actions.
After you have installed a PIA, you may need to restart both the Keyboard Maestro Editor and Engine in order for the new PIA to be recognized by Keyboard Maestro.
To insert a PIA into your Macro, use any of the normal methods to insert Actions:
Enter the PIA form fields (parameters) that are shown on the action form.
There is no easy way to create a Plug In Action. There is no one editor (except maybe BBEdit) that can be used to create all of the files that are needed. Probably the best way to get started is to examine an existing PIA, like this one:
Steps to Create a PIA
.ziparchive from the PIA Folder.
A Plug In Action is Contained in a Folder,
The PIA folder contains a set of files, including:
The PIA Folder must be stored as a
.zip archive file for installation.
The format of the Keyboard Maestro Action.plist is a Cocoa Property list containing a dictionary with the following keys and values:
|Name|| Name of the action.
(which appears in the Category/Actions list)
|Script|| Name of the script file which will be run when the PIA is executed.
The name can only use ASCII alphanumerics or underscores, plus an ASCII alphanumeric extension
|Parameters|| An array of parameters to the script
|Icon|| Name of the icon png file, made up of only ASCII alphanumerics or underscores plus .png
|Title|| The title displayed on the action
|Timeout|| The default timeout in seconds
|Author|| The author of this action
|URL|| URL for the author or this action
|Help|| A short (Tool Tip) explanation of this action
|Results|| What to do with the output of the script if any.
Multiple values can be used, separated by a bar (|), the first specified value is the default
|Label|| Name of the parameter.
|Type|| Type of the parameter.
Must be one of the following:
(Text in italics is info, and not part of the Type)
The Type specifies how the value is displayed to the user and what processing is applied before it is passed to the script.
|Menu|| Values of the popup menu, separated by |
Optional unless Type is PopupMenu.
|Default|| Default value of the Parameter when the PIA is inserted in the Macro.
Each parameter in the Parameters array is a dictionary with the following keys:
Warning: Keys are case sensitive.
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.
spaces in the variable names must be replaced with
underscores in your script.
Methods To Retrieve Parameters Using AppleScript
--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --» 1. Use AppleScript "system attribute" --~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- This method is "not safe for international characters" (and emoji) set myText to system attribute "KMPARAM_My_Text" --~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --» 2. Use Shell Script with "echo" --~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- This method works with emoji and international characters -- but multi-line text (as from a TokenText form field) -- will be flattened into a single line set myText to do shell script "echo $KMPARAM_My_Text" --~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --» 3. Use Shell Script with "printenv" --~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- This works with emoji, international characters and multi-line text -- however printenv returns an error if KMPARAM_My_Text doesn't exist. -- You can catch this error with a try command. try set myText to do shell script "printenv KMPARAM_My_Text" on error -- Parameter does NOT exist set myText to "" end try
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
If the Plug In script fails, the action will fail (v9.0+), potentially aborting the macro.