How to create a robust and reliable Keyboard Maestro macro

Building a reliable macro can be challenging if you have to run a series of sub-macros together. I’ve written my fair share of macros and put together a series of tips to help you efficiently build and debug a macro.

Setup The Macro Default State

You want to set a consistent default state if you’re building a macro that involves a series of sub-macros. Setting a default state is like moving the chess pieces to the starting position after you’ve finished the game.

Setting a default state is essential if the macro you build needs to deal with multiple application windows running in full screen.

Here is an example.

You want to set up a workspace that involves creating and resizing multiple Safari windows on a different screen. The default state will be a Safari application with all the windows closed. The macro will start by pressing Command-Option-Q to quit and close all windows.

The same can be said when you’re building a macro that pulls data from the spreadsheet tab and enter them into a different application. The default state is to close irrelevant documents and browser tabs. Then you can launch the applications for the macro to run.

Set Between Actions Delay

Another common problem with macro is that they can run too fast. Sometimes the application won’t be ready to respond to your macro in time and create unexpected behaviors. For example, the macro will type the value before the input field is focused.

The workaround is pretty simple. You can set an action delay between macro to 0.2 seconds at the beginning of the macro. Play around with the value until you can ensure that the macro runs consistently.

You can also resolve these unexpected behaviors by implementing control flows. I’ve published a collection of tips to help you build your first macro before. Although it hasn’t been updated for a while, these tips are still relevant today.

Declutter with Local or Instance Variables

Variables are wonderful pieces of Keyboard Maestro. You can use it to combine a series of macros to build a simple application.

The common mistake with people new to Keyboard Maestro is saving variables globally. You can check if you’ve been using global variables by opening the Preferences Variables settings. Most of the time, you don’t have to expose those variables to every macro.

The solution for the problem is to prepend Local or Instance to the variable so it’s available only for the executing macro during the runtime.¹

The difference between these two is how accessible they are to the executing macro. Most of the time, you can use local variables, but you want to use instance variables when:

• You want the variable accessible by the sub-macros from the executing macro.
• You want to keep the variable unique for each execution. For example, assuming you have a macro where you save file name to a variable called InstanceFileName. You can run the macro multiple times and each InstanceFileName will be unique even if macros run concurrently. Instance variables are useful when you have a macro that does many things in the background and you prefer not to wait for them to run sequentially.

Debug with Value Inspector

Once you start chaining multiple actions together, you will notice that you often need to check the value of the variables or tokens you plan to use. Keyboard Maestro has a built-in inspector where you can preview the value of variables. You can enable them by pressing Command - 6 or selecting it from Window - Value Inspector.

Keyboard Maestro also comes with a variety of tokens that you can use to set up your macro. A common token you want to use is the ICUDateTime token, where you can customize the date format. For example, you can enter %ICUDateTime%yyyy-MM-dd% in the inspector to see what it looks like before implementing it in the macro.