Applicable taxes will be added to the purchase price.
You can get your license and upgrade details from the Keyboard Maestro web site.
To upgrade from the Mac App Store version, you first need to transfer your license to a direct download license. You do that by launching Keyboard Maestro, opening the About box, and Option-clicking on the “Mac App Store version” text, and then following the instructions.
After that, you will have a direct download version and can upgrade to Keyboard Maestro 6 for $25.
No, Keyboard Maestro 9 requires 10.11 or later.
Yes, Keyboard Maestro is fully compatible with El Capitan.
Keyboard Maestro does not install anything on your harddisk, and uses public APIs, so the security measures added to OS X in El Capitan do not affect Keyboard Maestro's facilities.
Yes, Keyboard Maestro is fully compatible with Sierra. In fact, Keyboard Maestro versions going back as far as version 2.x still work fine on Yosemite.
Keyboard Maestro 7.x, 8.x and 9.x have no known issues with Sierra.
Keyboard Maestro is fully compatible with High Sierra, however for some very small set of people the Keyboard Maestro Engine can sometimes crash after sleep. This crash is caused by a very low level bug in the system software, resolved in 10.14 Mojave. Relaunching the Keyboard Maestro Engine (by launching Keyboard Maestro or by selecting File ➤ Launch Engine) will restart the engine and allow the macros to be processed.
Yes, Keyboard Maestro is fully compatible with Mojave. In fact, Keyboard Maestro versions going back as far as version 2.x still work fine on Yosemite.
Mojave has bugs with its Accessibility System Preferences which may require toggling the Accessibility permissions of Keyboard Maestro Engine off and on again. Generally this is only required once when upgrading to Mojave. See the Accessibility Permission Problem assistance for more information.
Note that Mojave adds some nagging for security permissions that can be tedious when first using Keyboard Maestro or when first controlling a specific facility or application.
Keyboard Maestro is believed to be fully compatible with Catalina. Versions of Keyboard Maestro prior to version 4.0 will no longer run on Catalina due to it dropping support for 32-bit applications.
Catalina appears to continue with the bugs with its Accessibility System Preferences introduced in Mojave which may require toggling the Accessibility permissions of Keyboard Maestro Engine off and on again, and/or deleting the Keyboard Maestro Engine preference from the Accessibility system and having it re-added. Generally this is only required once when upgrading to Catalina. See the Accessibility Permission Problem assistance for more information.
Note that Mojave adds lots of nagging for security permissions that can be tedious when first using Keyboard Maestro or when first controlling a specific facility or application.
Catalina is still in beta testing at this time, so the final details of any issues are unknown.
If you think you have found a bug, please report it, and please include all the pertinent information, such as:
The more explicit you are, the easier it will be to either explain the problem or correct any issue.
Keyboard Maestro (v6+) includes built in support for syncing.
First, all except the first Mac will have their macros entirely replaced, so if you have different macros on each Mac you should export any unique macros for latter import after you have set up syncing.
Macro syncing is all or nothing, so all your macros will be on all your Macs, and you can edit them on any Mac. You can set a Macro Group to be disabled specifically on this Mac by editing it in the editor.
As long as you don't make changes on two Macs faster than Dropbox syncs you will not get any conflicts, but if you do, Dropbox will save a conflict file and one or other change will be lost. You will probably need to periodically delete any conflict files Dropbox generates.
Make sure Keyboard Maestro and Keyboard Maestro Engine are not running on either Mac.
Transfer the ~/Library/Application Support/Keyboard Maestro folder, and optionally the ~/Library/Preferences/com.stairways,keyboardmaestro.* files (the latter include minor settings and preferences, as well as your license details).
Note that you can get to the ~/Library folder (which is hidden by default) in the Finder by holding down the Option key and selecting Go ➤ Library.
Make very sure that the resulting files and folders on your new Mac have the correct ownership and permissions.
The API for the Touch Bar does not appear to allow non-front applications to affect the Touch Bar, except that Apple does this themselves in Xcode and Screen Capture and the like. So Apple knows and understands the need, but have not made the facility available for Third Party macro trigger style applications.
The Keyboard Maestro (v8+) editor supports the Touch Bar in the future for use within the editor.
Keyboard Maestro (v8+) includes some Touch Bar actions (Show Palette of Macros action and Get Touch Bar Selection action) and allows you to have Conflict Palettes show up in the Touch Bar (though the limited space may make this impractical in practice).
Because of Apple's restrictions, actions showing in the Touch Bar require that the current application loses keyboard focus, which is not ideal but may not be a problem.
Asking Apple to add Third Party APIs for the “Control Strip” section of the Touch Bar would be a good idea.
Keyboard Maestro Control lets you trigger macros on your Mac from your iPhone/iPod touch or iPad.
See Keyboard Maestro Control for more information.
Note that generally the Remote trigger is a better solution that Keyboard Maestro Control, which has not been updated in many years.
Keyboard Maestro does not (automatically) restore the system clipboard after any operation that uses it (Insert Text by Pasting, Copy to or Paste from Named Clipboard, etc) because it cannot be done without incurring a race condition which will sometimes give the wrong results.
The reason is that while the clipboard can be read or set at any time, Copy or Paste can only be done via the Keyboard Maestro event queue (the keyword being “queue”). There is no way to know for sure when the application has processed the Command-V for a Paste operation, and thus no way to know when to restore the clipboard to its original value. If the system clipboard is restored too early, the wrong thing will be Pasted. If the system clipboard is restored too late, you may have already copied something else (manually or via another macro).
Instead, Keyboard Maestro provides a clipboard history and gives you control. Most of the time, you wont be using the clipboard and wont notice that it has been replaced, and if you do need it, you can get the old value back from the clipboard history. But if a macro is used where you frequently are finding that you need the system clipboard preserved, then Keyboard Maestro provides the tools for this. After your clipboard mangling action, add an appropriately long Pause followed by a Delete Current Clipboard action. The length of the Pause will depend on the target application and the speed of your Mac at that moment, and you will have to be aware that there is a period of time where you should not copy something.
See also the next question.
There are three ways to type text in Keyboard Maestro: Insert Text by Typing, Insert Text by Pasting, and Type Keystroke.
The Type Keystroke action lets you type a single keystroke, pretty much any kind of keystroke you can type on the keyboard.
The Insert Text by Typing action converts plain (simple) text into keystrokes and then types each of them individually. It only works with characters that can be typed with one or two keystrokes, so should work on most characters, but some characters are not typable with two keystrokes.
The Insert Text by Pasting action sets the clipboard to the text and then types a Command-V keystroke.
Each action has its advantages and disadvantages:
Type Keystroke. Advantages are it is just like typing yourself, so you can type any keystroke. Disadvantages are that it is quite tedious to do a sequence of them.
Insert Text by Typing. Advantages are it is just like typing yourself, particularly in relation to characters like tab/return, and to the current style in the text you are typing. Disadvantages are that it is slow for large amounts of text, and can't type unusual characters.
Insert Text by Pasting. Advantages are it is fast for large text, and can include any kind of characters. Disadvantages are that it overwrites your clipboard, and how styles are handled may be different to what you expect.
Use Type Keystroke when
Use Insert Text by Typing whenever:
Use Insert Text by Pasting when:
You should use Typed String triggers for macros that will interact with a text field. You should generally not use Typed String triggers for things that have some sort of global action (like launching an application or opening a URL).
This is because Typed String triggers work by you typing normal characters, and then usually Keyboard Maestro will issue the “Delete” characters to remove them, and then move on to executing the actions in the macro.
This means that you should only be using the Typed String triggers in a case where you are in a field that can accept typing. For example, if instead you typed them in the Finder (when not renaming a file for example), first the characters you type would select a file, and then Keyboard Maestro would simulate a delete and trash the file.
Even if you turn off the “Delete Characters”, the characters you type are still going to be going to the front application, so you still generally want to be in a text typing context, otherwise the typed characters will beep, or perform weird behaviours (like the aforementioned selecting of a file in the Finder).
So, you only want to use Typed String triggers in cases where you know you will be typing anyway. Where as a macro that opens a document, URL, application, whatever, is the sort of action you might want to do from anywhere, from the Finder, or while reading email, or whatever. You might well not be in a text typing context, and as such as Typed String trigger is typically a bad choice for the trigger.
Better is to use a Hot Key trigger (so the key is swallowed), the status menu or a macro palette trigger.
There are three kinds of palettes in Keyboard Maestro:
So to have more than one macro palette, create a macro group for each desired palette and configure it to show a palette as desired. Put your macros in there. Create as many of these as you like.The macros in such a macro group are only active while the palette is displayed, so if you only display it occasionally, especially only for one action, then they can have very simple hot keys (like plain letters for example).
You can control the order of macros in a macro palette (or the status menu) by prefixing their name with a code like “xx)” (eg “01)”). The macros will be sorted based on the code, but the code will be stripped off before display in the palette (or status menu).
You can assign multiple macros the same hot key, and Keyboard Maestro will display a palette of the conflicting macros when you press that hot key. You can then use number keys or the mouse, or the first significant letter to select the desired hot key. This is especially useful when you have a variety of similar or related tasks. You can also assign a hot key to a macro group which can activate it for one action (with or without a palette), and the contained macros can have whatever ”second” hot key you desire.
A Macro Group can be activated for one action after you press an initial hot key (optionally displaying a palette of its macros), allowing you to specify any second trigger you like.
A macro can use the Activate Macro Group for One Action action to explicitly activate another macro group for one action, allowing any complex chaining of hot keys.
There is a Typed String trigger, which takes a series of typed characters and then optionally deletes them, but this is restricted to typed keystrokes, so no Control or Command modifiers.
And finally, macros can enable and disable other macros or Macro Groups, allowing all sorts of possible control.
But Keyboard Maestro does not directly support assigning a two-keystroke hot key to a trigger. The problem with multiple keystroke triggers like Option-F R is what to do if you type Option-F A?
Logic dictates that the Option-F A should go through to the system unimpeded, but Option-F R should be swallowed entirely. But this is impossible. The only way to do it would be to swallow the Option-F key, and then swallow the second key and then resubmit the Option F and the second key unless it matches Option-F R.
However, that is fraught with peril and cannot work robustly in the presence of other applications placing things on the keyboard event queue (or even a sufficiently fast typist).
For example, suppose you quickly typed Option-F A B. Keyboard Maestro would have swallowed the Option F and then the A, and then resubmitted it to the event queue, resulting in the stream of characters B, Option-F, A. There is no way to avoid this race condition, and as such Keyboard Maestro does not support any such mechanism.
As described above, Keyboard Maestro has a variety of ways you can use Option-F as a hot key that allows a second key to be used to select a macro. However in all cases it is clear that the Option-F has been used and there is no concept that the Option-F might come back later to do something else.
Basically, no. The Fn key is not a modifier, it is a hardware toggle that toggles whether the physical key behaves as a function key (eg F3) or a hardware key (eg increase brightness). Its behaviour can be toggle in the System Preferences, Keyboard preferences. You can use a function key as a trigger as long as it is behaving as a function key (that is either with or without the Fn key depending on your system preference setting). But the Fn key does not affect the hot key per se, it changes whether the key on the keyboard acts as a function key (needful for hot keys) or a hardware key (which cannot be used with a hot key).
Think of your keyboard as have two rows of keys, one row of function keys and one row of hardware keys - the Fn key toggles which row is “visible”.
You cannot really do this with Keyboard Maestro.
Keyboard Maestro has two primary key triggers: hot keys and device keys.
Hot keys intercept and swallow the key press but cannot distinguish between the same key on different keyboards.
Device Keys can distinguish the key on different keyboards, but do not swallow the key so the key continues to perform its normal function.
So you could use all the function keys (with associated modifiers) on both Macs using a device key trigger. But you could not use, for example, the “a” key on a second keyboard without also typing an “a” (or swallowing both a's if you used a hot key).
An alternative is to use a non-keyboard keyboard, something like an XK-24 or the like, that does not perform any normal function. You can use device key triggers with that kind of keyboard.
Also, with version 9, Keyboard Maestro adds direct support for the Stream Deck, including the ability to trigger macros as well as control the image and title of the buttons.
In Keyboard Maestro, there are two kinds of processed fields, text token fields and calculation fields. Most text fields are the text token fields. Most numeric fields are calculation fields.
A small indicator appears (v8+) in the field when you are editing to tell you what kind of field it is, Token, Calculation, or Variable.
Text token fields typically (but not always) have an Insert Token pull down menu, and are always quite long. They are designed to allow you to enter text, rather than a numeric value.
In these fields, you use text tokens, which are marked with percents, like %CurrentClipboard% or %Variable%My Variable%. You can insert a text token from the Insert Token popup menu, or by selecting from the Edit ➤ Insert Text Token menu.
Calculation fields are usually small to start off with (assuming they contain only a number), and usually have a stepper (double arrows) next to them. They are designed to allow you to enter a numeric value.
In these fields, you type a raw calculation. As soon as you type anything other than a digit, they expand to a larger size to allow for a calculation. Calculation fields never use percent tokens, but they can include variables or functions. You can insert a function or variable by selecting from the Edit ➤ Insert Function menu.
If desired, you can include a calculation in a text token field by using the %Calculate% token like this: %Calculate%1+2%.
If desired, you can include a tokens in a calculation field by using the CALCULATE function.
One more thing to note, variables can contain an array of comma separated numbers, like the image size (123,456) or window frame (100,120,600,550). In a calculation field, you can refer to these using a normal (1-based) index notation, like Variable. So you can use ClipboardImageSize and ClipboardImageSize. In a text field you can use %Variable%ClipboardImageSize%.
For example, the Display Text action field is a text field, and is parsed for text tokens. It can optionally uses the %Calculate% text token to evaluate expressions, whereas the Draw a Shape action fields are calculation fields, so no text tokens, just raw calculations.
The system has a variety of things people call hot keys or shortcuts or command keys, but there are actually several different kinds. The main kinds are:
Keyboard Maestro has special code to work around Command-Tab's Event Tap system hot key.
On top of that, when multiple identical Hot Keys defined within Keyboard Maestro are active, when you press that key Keyboard Maestro will activate the Conflict Palette instead and let you select which macro you wish to trigger.
Selecting status menu items is difficult primarily because there is no easy way of specifying them - they don't have names so its hard to identify them.
You can use a Click at Found Image, although even that can be difficult as they often animate or change icons based on various states. If the icon does not animate or change state (or has a known state when you want to select from it), then this can be a good solution, followed by Insert Text by Typing “Menu Name%Return%”
To click relative to an image, you use the Mouse Click action, configure it to be relative to a found image, and take a screenshot of the desired area of the screen using Command-Control-Shift-4, and paste it into the image well on the action. The image has to be unique (which includes not being visible in the action if the image is small enough not to be shrunk in the image well) otherwise Keyboard Maestro will not know where to click. The Display option in the action will allow you to see where Keyboard Maestro is matching.
Keyboard Maestro 5 introduced variables to its set of features. These variables are really great for us scripters! They are implemented in a way that a variable can be initiated from within Keyboard Maestro (A Prompt for User Input, Set Variable to Text, or a Set Variable to Calculation action.), which can then be used in other actions such as Shell and AppleScript scripts. One variable, manipulated with everything your Mac has to offer.
Variables can be used with the
%Variable%variable name% syntax. Calculations, such as screen coordinates and frames, whether the Mac is online, Safari tabs, etc, can also be used for some nifty things, and they can set variables! There's a lot to check out with calculations. Calculations, can even have two elements, in which case the variables can be accessed as array. (
In Shell and AppleScript's this looks similar. Please refer to the documentation for this. A Shell script can access variables like so:
$KMVAR_variable_name or so
$_ENV[“KMVAR_variable_name”] (_ is an underscore character).
Which brings us to the point of this article: naming best practices.
Variables that start with “Local ” (v8+) will be local to the macro in question, and that start with “Instance ” will be local to the macro instance (ie, that macro and all the macros that it executes). Consider availing yourself of these local variables if appropriate.
Keyboard Maestro variables can have whitespace characters in their name. This is good for human readability. It also makes for better user experience in User Input dialogs. Whitespace characters are converted to underscores in scripts. From a Shell or AppleScript'ers point of view these don't look “natural”.
Regular Expressions are a powerful tool for text processing and are fully supported in Keyboard Maestro. You can use regular expressions to extract or change parts of text or dates or file names.
You can learn more about regular expressions in various places: * The BBEdit or TextWrangler Help has extensive documentation on regular expressions. * gskinner’s RegExr provides a live testing field for regular expressions (requires Flash). * Beginning Regular Expressions book. * Mastering Regular Expressions book. * Regular Expressions Tutorial online resource.
The Keyboard Maestro editor is designed to be run only when needed, and then quit.
You can (v8+) click the close box on the editor window and it will quit the editor for you.
The Keyboard Maestro Engine will continue running and processing your macros after you quit the Keyboard Maestro editor. Read the Quick Start for more details about the difference between the editor and the engine.
The system adds an alert to tell you when an application is accessing the Address Book, but unfortunately, that alert does not distinguish between an application reading your “My Card” email address and an application reading your whole contacts database.
Keyboard Maestro accesses your My Card information only, for the purposes of pre-filling your contact information if you wish to subscribe to the Getting Started emails (highly recommended!), and for the use in the AddressBook tokens (eg %AddressBook%First%). Keyboard Maestro does not directly access any of the remainder of your contacts database (although you can access them via AppleScript).
If possible, you should avoid using mouse click actions. They tend to be very fragile, easily broken by subtle changes to the system or applications. And they also require the screen to be in the expected state, so you usually need to add a Pause action before them to ensure the item they are clicking on is where it is expected to be.
That said, there are two easy ways to get the screen coordinates for a mouse click.
The first is to simply record the click. Turn on recording in Keyboard Maestro, go to where you want to be, wait a could seconds for the screen to be stabilised so the click will be relative to the front window, and click. Turn off recording, delete any extraneously recorded actions and you have your coordinates.
Alternatively, use the built in Mouse Display (Help ➤ Mouse Display) which will show the screen coordinates relative to any corner of the main screen or front window.
In Keyboard Maestro, in the General preferences, select Never as the Display Status Menu popup menu.
Unfortunately, Apple have provided no control or API over the Spaces system, so unfortunately Keyboard Maestro cannot help you control which Space an application or window is in.
Selecting from a popup menu is difficult, largely because it is difficult to specify which popup menu button you mean. To select from a popup menu button, there is two parts, first you need to make the menu popup up, and then you need to select the menu item. To popup the menu of a popup menu button, there are several possible methods:
Once you have popuped up the menu, selecting it is relatively easy. Use a combination of arrow keys, text typing (using the Insert Text by Typing action) and the Return key to select the menu. Usually just Insert Text by Typing “Menu Name%Return%” will work, though sometimes you will need to us e an initial down arrow, and for hierarchical menus, you will need to use right arrows to open each level.
Keyboard Maestro executes multiple macros simultaneously.
So say you have a macro that looks like this:
Trigger: F1 Actions: Click Here Pause 1 Second Click There Pause 1 Second Click Elsewhere Pause 1 Second
And that does something and works fine.
But if you press F1 three time quickly the sequence is going to look something like this:
Click Here Click Here Click Here Click There Click There Click There Click Elsewhere Click Elsewhere Click Elsewhere
If that is what you want, that's fine, but probably you want the clicks to be in the sequence Here,There,Elsewhere, repeated three times.
This is where a Semaphore comes in. If you don't know what a Semaphore is, you can read about them on Wikipedia (Keyboard Maestro uses a binary semaphore, either locked or unlocked).
So if you add a Semaphore Lock to the start of the macro and a Semaphore Unlock to the end of the macro (the latter is optional as Keyboard Maestro will automatically release all the semaphores held by a macro execution when it finishes), then the macros would be executed sequentially.
You can cancel all running macros by holding all the modifiers down (Command, Control, Shift, Option) and clicking in the Keyboard Maestro status menu.
You can cancel specific macros by selecting from the Cancel submenu in the Status Menu, or by selecting Start Debugging in the Status Menu, and clicking the appropriate cancel buttons.
There are also actions for Cancelling All, This, or Other Macros, which you can use and trigger in any way you like.
Keyboard Maestro is no longer available from the Mac App Store.
The Mac App Store had only version 5. It is an old version and you should not buy Keyboard Maestro from the Mac App Store.
The Mac App Store requires sandboxing for any non-bugfix updates (Apple's requirement). and this excludes workflow applications like Keyboard Maestro, so version 5.3.2 will likely be the last version available on the Mac App Store.
Keyboard Maestro is no longer available from the Mac App Store.
As of June 2012, Apple now requires sandboxing of any application before it can be updated (other than bug fix updates) on the Mac App Store. Since the Apple entitlements available to a sandboxed application are entirely insufficient to allow Keyboard Maestro to perform many of its operations, Keyboard Maestro cannot be sandboxed. Everything Keyboard Maestro does is strictly part of the standard system APIs, but Apple simply has not provided the entitlements required to do the things Keyboard Maestro does from within a sandbox. So as it stands, Keyboard Maestro will not be able to get anything more than minor updates on the Mac App Store, and version 5.3.x will be the last version available through the Mac App Store.
Although it is possible to transition your license from the Mac App Store version to a direct license by contacting Stairways, it will cause some disruption.
Keyboard Maestro is no longer available from the Mac App Store, so you cannot buy from the Mac App Store.
You could never buy any version from version 6 onwards from the Mac App Store.