KM-Builder: a command line tool for managing Keyboard Maestro actions

Plug In Actions
1

Hi All,

I'm excited to share km-builder, a powerful command-line toolkit that makes managing your Keyboard Maestro third-party plugins.

Here are some main benefits:

  • Streamlined Action Management: Initialize, build, install, and manage your Keyboard Maestro actions with simple command-line commands. No more digging through folders or manual file copying!

  • Smart Dependency Management: KM-Builder automatically detects and handles Homebrew dependencies for your actions. It'll ensure all required components are installed properly, saving you from troubleshooting headaches.

Would love to hear your feedback and thoughts and welcome contributors.

Please have a look:

Release

1 Like
2

I think it would be helpful if you would provide an example action.

3

Great feedback.

Here is an example scenario:

Create ability to read XMP metadata

I want to write a plugin that allows me to read XMP metadata data from an image file. I am going to use km-builder to help me make that.

In Terminal:

km-builder init
Enter the folder name: km-exiftool-read-metadata
Folder 'km-exiftool-read-metadata' already exists.
Name (default: Folder Name 'km-exiftool-read-metadata'): Read metadata in image
Results (None, Window, Briefly, Variable, Clipboard, or all): None, Window, Variable, Clipboard
Timeout (default: 30): 
Help: A utility that allows you to read XMP metadata from an image file like keywords, title, description, etc.
Script Language (AppleScript/Shell): Shell
Author: Autobot
Group (optional): 
Homebrew dependencies (comma-separated, optional): exiftool
Do you want to add a parameter? (Yes/No): Yes
Parameter Label: File
Parameter Type (default: TokenString): TokenString
Default Value (optional):   
Do you want to add a parameter? (Yes/No): Yes
Parameter Label: Tag
Parameter Type (default: TokenString): 
Default Value (optional): Title
Do you want to add a parameter? (Yes/No): no
Plist file created: Keyboard Maestro Action.plist
Icon file copied to the action folder.
Shell script file created: Action.sh
Do you want to open the folder in VSCode? (Yes/No): Yes

This will result in a folder that includes an Action.sh, Icon.png, and Keyboard Maestro Action.plist.

You can then put whatever the script is into the Action.sh file. In this example:

#!/bin/bash

EXIFTOOLPATH="/opt/homebrew/bin/exiftool"
PARAMS="-s -s -s -m"

# Check if exiftool exists and is executable
if [[ ! -x $EXIFTOOLPATH ]]; then
    echo "exiftool is not installed. Please install via Homebrew."
    exit 1
fi

# Validate file path
if [[ -z "$KMPARAM_File" || ! -f "$KMPARAM_File" ]]; then
    echo "Invalid or missing file path: $KMPARAM_File"
    exit 1
fi


# Execute the appropriate exiftool command based on the metadata field
$EXIFTOOLPATH $PARAMS -$KMPARAM_Tag "$KMPARAM_File"

Then, if I want to install this plugin in Terminal:

km-builder install km-exiftool-read-metadata 
Copying folder 'km-exiftool-read-metadata' to Keyboard Maestro Actions.
Folder 'km-exiftool-read-metadata' installed successfully.
This action has the following dependencies: Array {
    exiftool
}
Would you like to install these dependencies using Homebrew? (Yes/No): Yes

This will copy the file into the Keyboard Actions Plugins folder in Library and then ask if you want to install the Homebrew dependencies.

image
image1269×179 24.2 KB

3 Likes
4

km-exiftool-read-metadata.zip (8.0 KB)

Here is also the sample generated one from above.

Note that in the .plist file you will also find:

<key>HomebrewLibs</key>
	<array>
		<string>exiftool</string>
	</array>

Which then has all the dependencies it will install from homebrew.

5

Installing plugin actions is fairly simple right now. What benefit does this add? Please be specific - rather than sharing code, explain an example of a plugin action that could take advantage of this.

6

Hi Dan,

Thanks for asking. There were a few problems I was trying to solve:

Developing new plugins

As I was learning how to develop plugins for Keyboard Maestro, I was reading a number of the different pages and was finding that I had to take time to learn the structure. I wanted to have an easy way to create a new plugin with the right structure, plist, etc.

Installing dependencies

Many of my plugins I have been building also leverage a number of dependencies that are libraries from homebrew, so I wanted to find a way that easily also installs the dependencies as well. I added to the plist that the dependencies in homebrew can then be included in there so as part of the installation it then can install any of the dependencies.

Repositories

I see that there are a number of samples that are posted to the forums. However, I wanted to go in the direction where those plugins could be managed in places like GitHub. I want to then be able to install easily rather than having to download from forums. I haven't implemented this yet, but it would be like homebrew, apt-get, etc. so you can just install from a library of different plugins easily by name.

This would also then allow the possibility of allowing updating, so each of those plugins could have their repositories and a .km-builder update could go and update those repos.

Again, not something that I have entirely implemented yet, but that is the thought.

Enable/Disable/Install/Uninstall

Currently, to enable and disable requires me to remove the folder from Application Support, then tell the Keyboard Maestro Engine to update. By using the Terminal, then allow for me to uninstall or update and it will automatically update Keyboard Maestro. This is particularly helpful during development.

I will also note that I think there are opportunities that could even be in product that could be great opportunities such as:

A plugin exchange
A UI for enabling and disabling
Allowing plugins to have a repo so that it updates

But I am looking at it via Terminal because I am doing a lot of different plugins.

1 Like
7

How does that relate to 3rd party plug-ins for KM?

8

Apologies. I’m not sure how Automator slipped out when I was writing that one because I haven’t even built plugins for Automator. I corrected my post. I was building 3rd party plugins for Keyboard Maestro.