User Tools

Site Tools


manual:How_do_I

**This is an old revision of the document!**

How do I ...?

How do I install Keyboard Maestro?

To install Keyboard Maestro, simply copy it to your Mac’s Applications folder (or anywhere you like).
Note: You must use the Finder to do this will turn off Apple's App Translocation security feature when you move the application with the Finder.

When you launch Keyboard Maestro it launches an invisible “Keyboard Maestro Engine” that continues to run even after you quit Keyboard Maestro. The engine is the process that enables your Macros, Application Switcher, and Clipboard History Switcher to work. This means that they will continue to work after you quit Keyboard Maestro, as long as the engine is still running.

You can quit or launch the engine manually using the File menu.

You should consider turning on the “Launch Engine at Login” preference in the General preference pane to ensure all of Keyboard Maestro’s facilities are available to you as soon as you login or startup your Mac.

How do I upgrade Keyboard Maestro?

Keyboard Maestro includes an automatic upgrade mechanism, so to upgrade Keyboard Maestro simply click the Install Update button when prompted.

To upgrade Keyboard Maestro manually, quit the engine by choosing Quit Engine from the File menu and the editor, and replace the Keyboard Maestro application in your Applications folder with the new one. Finally, launch Keyboard Maestro to restart the engine.

Keyboard Maestro will automatically import your previous version macros, clipboards and preferences. Your old macros will be saved in the ~/Library/Preferences/Keyboard Maestro/Keyboard Maestro Macros Saved Version 7.plist in case you wish to revert to version 7 for any reason.

If you are upgrading directly from a much older version, you will get better results by upgrading to the last of each major version in turn, ie, run 2.1.3, then 3.5, then 4.3.2, then 5.3.2, then 6.4.8, then 7.3.1, then the current version. You can download old versions from our file archive.

How do I purchase Keyboard Maestro?

New customers can purchase Keyboard Maestro for US$36 by choosing Purchase Keyboard Maestro from the Keyboard Maestro menu. Customers with five or more users should contact us for a volume discount quote.

You can look up your current or previous license status and serial numbers, and get information about discounted upgrades from https://enquiry.stairways.com/.

Thanks for supporting us and enabling us to continue work on Keyboard Maestro.

See also the Purchase section.

Can I purchase Keyboard Maestro from the Mac App Store?

Keyboard Maestro will not be available on the Mac App Store. Apple requires applications on the Mac App Store to be  Sandboxed, and workflow applications like Keyboard Maestro cannot be sandboxed so it is excluded from the Mac App Store.

See also the Purchase section.

How do I register Keyboard Maestro?

When you purchase Keyboard Maestro you will be given a serial number, and will also promptly be emailed your username (email address) and serial number in the “Thanks For Your Purchase” email. Although you can retrieve this information from us at any time in the future, it is a good idea to keep this safe.

If you do not receive your serial number promptly after purchasing, it may be that the email has not reached you, possibly due to spam filtering on your email service. In this case, try looking up your purchase at https://enquiry.stairways.com/ (although that will email you your serial number which might again be lost to over-zealous spam filters).

Once you have your username (email address) and serial number, launch Keyboard Maestro and either immediately click the Use Existing License button or choose Register Keyboard Maestro from the Keyboard Maestro menu and then enter the username (email address) exactly as shown and the serial number exactly as shown and click the OK button. If you have any problems, recheck that the email address and serial number you are entering are exactly as shown (the serial number’s email address does not change even if you have changed your email address with us) and also that your license matches the major version number (eg, a version 7 license will work with version 7.x of Keyboard Maestro). If there is not Register Keyboard Maestro menu, it is because you have already registered this copy of Keyboard Maestro - choose About Keyboard Maestro from the Keyboard Maestro menu and check that the About box says you are registered.

How do I get started?

The first thing to do is to read the Quick Start and do the tutorial by choosing Tutorial from the Help menu. You may also want to subscribe to our Getting Started emails (Keyboard Maestro will ask you to subscribe or you can do that at your customer database page on our web site).

After that, use your Mac normally and keep an eye out for things you do repetitively. Things like:

  • launch or switch to a particular application.
  • open a particular document.
  • type a specific string of text (eg your name, address, etc).

When you notice something, consider making a Macro to do it and assigning it to a Hot Key or a Macro Palette or Status Menu trigger.

Try to be consistent with your Hot Keys, for example you might have a set of applications you open, using a function key for each, and a set of documents you open, using a Control-Function Key combination for each of them, and a bunch of snippets of text your type, using Control-Letter for each of them (the letter could be a mnemonic to help you remember which one is which). Consider putting a sticker on your keyboard across the top of your function keys to help you remember which ones do which function. Remember that you can use the number pad keys as well.

Also, keep in mind common command keys and system defined hot keys and try to avoid conflicting with them.

See also the Tips section.

How do I create a new Macro?

If you have not done so, use the tutorial by choosing Tutorial from the Help menu to lead you through the process of creating a simple macro.

To create a Macro, launch Keyboard Maestro and select the Global Macro Group, then click the + button under the Macros list. Give the Macro a name, add one or more triggers, and one or more actions. The Macro is immediately active — you do not need to stop editing, quit the editor or anything else.

An easy way to generate macro actions is to turn on recording and proceed to show Keyboard Maestro what you want to do. Then turn recording back off and look through the actions — chances are you will want to delete or adjust some of the recorded actions to make a robust macro, but this will give you a quick start on creating the macro.

How do I find a Macro I've used or modified recently?

You can sort the macros by name, by trigger, by date created, modified or used. So if you launch Keyboard Maestro, select the All Macros pseudo group, and then choose Sort Macros by Date Modified from the View menu (or choose Sort Macros by Date Used from the View menu) to sort the recently modified (or used) macros to the top.

You can also click the button above the macro editor pane to select from recently modified macros, or use the button to select from recently used macros.

How do I cancel a running Macro?

You can cancel all running macros by holding all the modifiers (Command, Control, Option, Shift) and clicking on the Keyboard Maestro Status Menu Icon.

You can cancel a specific macro by choosing Cancel from the Status Menu menu and selecting the macro. This is also a useful way of seeing what macros are currently running, if any.

You can also see and cancel macros by choosing Start Debugging from the Status Menu menu.

And finally, you can use the Cancel All Macros, Cancel Other Macros, Cancel This Macro, or Cancel Just This Macro actions.

How can I get the mouse coordinates on the screen or in a window?

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, you can use the Mouse Display window by choosing Mouse Display from the Window menu which will let you see the mouse coordinates relative to the window or main screen. Click the lock button to lock the display after a few seconds, and then put your mouse over the desired location. You can then change the relative corner, and click the Clipboard buttons to copy the coordinates.

Alternatively, you can simply record the click. Turn on recording in Keyboard Maestro, go to where you want to be, wait a couple 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. Immediately after recording you can adjust the relative corner of the window or screen, and the recorded coordinates will adjust to match.

Remember that offsets are always to positive to the right and positive down, so if you are making a mouse click up from bottom edge of a window or screen, or left from the right edge of a window or screen, you will need to use negative coordinates.

How do I insert styled/colored text or images?

You can use the Insert Text action to insert styled text by pasting.

You can insert an image by copying it to the clipboard and then pasting it in using the Paste action (which just types the Command-V keystroke).

You can get your image from a Named Clipboard, or by reading an image file.

Here is how to create a Macro to insert an image when you press a Hot Key.

Name the macro, and assign it whatever trigger you desire.

Now whenever you trigger the macro you just created, your image will be pasted in.

How do I Insert the current date?

You can insert text using the Insert Text action, and it processes Tokens. There are some basic date format tokens (such as %LongDate%), or you can use the %ICUDateTime% Token with any ICU date format.

How do I get more than one Macro Palette (Toolbar)?

There are three kinds of palettes in Keyboard Maestro:

  • There is one “Global Macro Palette” which includes any active macro that has the Macro Palette trigger. It appears whenever there is any active macro with the Macro Palette trigger. It shrinks to the size of an icon until you hover over it and then it expands to display the currently active macros with Macro Palette triggers. You can show and hide it using specific Macro Palette actions.
  • Each Macro Group can be displayed as a palette. The macro group can be global to all applications, or specific to any subset of applications. It can be toggled on and off with a hot key (or a status menu selection or from the Global Macro Palette) or it can be displayed for a single action. Actions can hide or show the macro group palettes.
  • When a hot key (or typed string or device key) conflicts (ie, triggers more than one macro), the Conflict Palette appears which lets you select from the conflicting macros. This can be an easy way to allow a single hot key to offer a multitude of similar actions. You can then use number keys or the mouse to select the desired hot key, or can use other keys to filter the palette until only one macro remains.

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 two characters and a closing parenthesis (eg “01)” - two characters and a closing bracket). The macros will be sorted based on the code, but the code will be stripped off before display in the palette (or status menu).

How do I use a multiple keystroke trigger?

You can assign the same hot key to multiple macros, and Keyboard Maestro will display a palette of the conflicting macros when you press that hot key allowing you to select the desired macro. You can select a macro from the palette using either number keys, or by typing the first distinct character to filter the macros down until only one is left. 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.

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.

How do I configure the Application Switcher?

The Application Switcher (and all the switchers) are activated by macro actions. Keyboard Maestro creates a default “Switcher Group” Macro Group containing several macros, each macro has a hot key trigger and a matching action which activates the appropriate switcher.

So to configure the Application Switcher, launch Keyboard Maestro, select the Switcher Group, and double click the Activate Application Switcher macro. You can then configure the various Application Switcher parameters, such as style and icon size by configuring the Application Switcher action. You can also configure the hot key used to activate the switcher, or disable the switcher.

How do I backup / transfer my installation to another Mac?

If you are going to continue using both Macs, you should use Macro_Syncing rather than transferring your information. And indeed you can use Macro Syncing to transfer to a new Mac (even if both Macs wont be on at the same time as long as you preserve the sync file).

To transfer all your information to a new Mac you can copy the ~/Library/Application Support/Keyboard Maestro folder and optionally the ~/Library/Preferences/com.stairways.keyboardmaestro.* files to your new Mac. You can get to ~/Library in the Finder by holding down the option key and selecting Library from the Go menu.

Make sure that Keyboard Maestro and Keyboard Maestro Engine are not running on the source or target Mac when you transfer the folder. And make sure the resulting files and folders have the correct ownership and permissions.

If you copy the com.stairways.keyboardmaestro.* files, the new Mac will have the same MacUUID token and be considered the same Mac for syncing purposes, so you should not do this if you intend to continue using the old Mac.

How do I uninstall Keyboard Maestro?

Launch Keyboard Maestro and ensure the “Launch Engine at Login” preference in the General preference pane is turned off. Then choose Quit Engine from the File menu to quit the engine, and then choose Quit Keyboard Maestro from the Keyboard Maestro menu to quit the application.

You can then trash the Keyboard Maestro application from your Applications folder, as well as the preferences in the ~/Library/Application Support/Keyboard Maestro folder and ~/Library/Preferences/com.stairways.keyboardmaestro.* files and logs in the ~/Library/Logs/Keyboard Maestro folder.

How do I revert to a previous version of Keyboard Maestro?

Launch Keyboard Maestro and ensure the “Launch Engine at Login” preference in the General preference pane is turned off. Then choose Quit Engine from the File menu to quit the engine, and then choose Quit Keyboard Maestro from the Keyboard Maestro menu to quit the application. You can then trash the Keyboard Maestro application from your Applications folder.

For version 2, open the ~/Library/Preferences folder and the folder ~/Library/Preferences/Keyboard Maestro/Saved Version 2 folder. Move the files from the latter folder into the former folder. Trash the ~/Library/Preferences/Keyboard Maestro folder. Download Keyboard Maestro 2.1.3, if necessary, from https://files.stairways.com/keyboardmaestro/keyboardmaestro-213.dmg. Move Keyboard Maestro 2 to the Applications folder and launch it. Turn on the “Launch Engine at Login” preference if desired.

For version 3, open the ~/Library/Preferences/Keyboard Maestro folder. Trash the Keyboard Maestro Macros.plist and replace it with the Keyboard Maestro Macros Saved Version 6.plist. Download Keyboard Maestro 3.5, if necessary, from https://files.stairways.com/keyboardmaestro/keyboardmaestro-35.zip. Move Keyboard Maestro 3 to the Applications folder and launch it. Turn on the “Launch Engine at Login” preference if desired.

For version 4, open the ~/Library/Preferences/Keyboard Maestro folder. Trash the Keyboard Maestro Macros.plist and replace it with the Keyboard Maestro Macros Saved Version 6.plist. Download Keyboard Maestro 4.3.2, if necessary, from https://files.stairways.com/keyboardmaestro/keyboardmaestro-432.zip. Move Keyboard Maestro 4 to the Applications folder and launch it. Turn on the “Launch Engine at Login” preference if desired.

For version 5, open the ~/Library/Application Support/Keyboard Maestro folder. Trash the Keyboard Maestro Macros.plist and replace it with the Keyboard Maestro Macros Saved Version 6.plist. Download Keyboard Maestro 5.3.2, if necessary, from https://files.stairways.com/keyboardmaestro/keyboardmaestro-532.zip. Move Keyboard Maestro 5 to the Applications folder and launch it. Turn on the “Launch Engine at Login” preference if desired.

For version 6, open the ~/Library/Application Support/Keyboard Maestro folder. Trash the Keyboard Maestro Macros.plist and replace it with the Keyboard Maestro Macros Saved Version 6.plist. Download Keyboard Maestro 6.4.8, if necessary, from https://files.stairways.com/keyboardmaestro/keyboardmaestro-648.zip. Move Keyboard Maestro 6 to the Applications folder and launch it. Turn on the “Launch Engine at Login” preference if desired.

manual/How_do_I.1503460116.txt.gz · Last modified: 2017/08/22 23:48 by peternlewis