Keyboard Maestro 9 added official support for the Elgato Stream Deck. The official plugin (documented here) is very powerful and allows for two-way communication between Keyboard Maestro and the Stream Deck. That said, it’s also relatively rigid and complicated. Rather than map a trigger to a button, you map a button to a trigger. This has a couple of downsides:

  1. If you want to reorganize your Stream Deck layout, you’ll have to go to every macro that you’ve assigned to a button and edit its USB Device trigger in Keyboard Maestro. What I want to do instead is just click and drag a button to move it in the Stream Deck interface.
  2. If you have lots of different Stream Deck profiles and/or folders, you have to start using the concept of “virtual” rows and columns where you assign your buttons on the extra profiles/folders a virtual row and column of something out of the normal bounds of the Stream Deck. This quickly gets unwieldy as you start managing several screens worth of virtual rows and columns.

My needs were simple; I sought a way to trigger a Keyboard Maestro macro with a single button press. I didn’t need the extra power of the two-way communication. So I sought a simple way to do that.

As it turns out, the Stream Deck has a limited ability to run AppleScripts and shell scripts. From what I was able to tell, it looks at file extensions; any .sh extension will be run as a shell script and any .scpt extensions will be run as AppleScript. I’ve tried this with other types of scripts (for example .pl for Perl scripts) and I’ve also tried to use Unix shebang interpreter directives but haven’t had much luck. It looks like shell scripts and AppleScripts are special cases.

All that said, here’s a simple step-by-step guide on my process (which I should automate) on assigning a Keyboard Maestro macro to a button without using the plugin. The magical bridge here, of course, being AppleScript.

  1. Select your macro in Keyboard Maestro and copy the auto-generated AppleScript or shell script to your clipboard.


  1. Open up a text editor and save the contents of your clipboard to a plain text file. in this example I’m using SublimeText but TextEdit or any other text editor will work fine. If you’re saving an AppleScript save the file with a .scpt extension. If you’re saving a shell script, .sh extension.


  1. Create an Open action on your Stream Deck and point it at the file you just created.


And that should do it!

This methodology avoids the two pitfalls I mentioned above. In this way, you get to rearrange your Stream Deck (which may include things other than Keyboard Maestro macros) and avoids the hassle of dealing with virtual rows and columns since the macro is bound to the button and not the other way around.

This is how I do things, and there is definitely room for automation. Furthermore, I would be remiss if I didn’t mention Corcules’ KMlink Stream Deck plugin. It’s an alternative to the default Keyboard Maestro plugin that works splendidly. It actually accomplishes all of what I do manually, but doing it my way means I’m in control of the whole system. When it comes to automation, I like to remove as many middlemen from the equation as possible so as to increase the probability that my setup works. Additionally, if my automations don’t work, doing things by hand like this means I’m more likely to be able to fix the issue.