Keyboard Maestro 5
Conduct your Mac Like a Pro!
A Macro executes a sequence of Macro Actions in order. There are many actions to choose from (detailed below), some simple actions, such as Sleep Computer, require no other information and simply do their job, while other more complex actions, such as Select Menu Item, require you to specify more information, such as a target application or menu name.
There are many powerful Macro Actions available for your use, and you can sequence them together to perform complex tasks.
To see all actions, select the All Actions category. To select just your favorite actions, select the Favorites. You can drag actions into your Favorites category.
Application Control actions allow your to switch, quit, or hide applications. The actions are:
Clipboard actions let you manipulate the system clipboard, Named Clipboards, the clipboard history and cut, copy or paste clipboard items. The actions are:
The Filter Clipboard action includes a number of filters you can apply to the clipboard (or correspondingly, the Filter Variable action can apply them to variables).
The filters are:
We will likely expand the list of possible filters, so if you have specific filtering needs that you think might be of general interest, please let us know. In the mean time, remember that you can apply scripted filters using an AppleScript or shell script, for example the shell script:
pbpaste | perl -pe 'tr/A-Z/a-z/' | pbcopy
is roughly equivalent to the Lowercase filter, except that it only works with ASCII characters.
You can control the flow of a macro execution using a variety of actions, from a simple Pause for a number of seconds, through a complex nesting of If/Then/Else and looping.
The actions to control the flow of a macro are:
You will often need to use the Pause action to slow down replaying of an action sequence to allow the system time to catch up—especially after you have changed application or if you want to use a mouse click.
The condition clause of the flow control actions can be any of:
If there are no conditions in the set at all, the action will not execute anything except the Until action which will execute the actions once. Neither side of the If Then Else will execute.
There is over a dozen different kinds of conditions, from testing what the current application is, through examining variables or the clipboard, and on to check your network location or testing a pixel on your screen, see the Conditions section.
The For Each action loops over a set of collection items, setting a variable to each value and executing the contained actions. The collections can include:
The control flow actions include a nested list of their own actions to execute, and that nested list can include further control flow actions—go wild! But keep in mind, there may be a time when a shell or AppleScript is a more useful way of describing your solution.
See also the Conditions, Variables and Calculations sections.
Execute actions let you execute AppleScripts, Shell scripts, Automator Workflows or another macro. Shell scripts can be any kind of script, sh, zsh, tcsh, perl, python, and so on. The actions are:
The results of an AppleScript or shell script can be ignored, or you can:
For example, you could have a shell script date display briefly in a HUD window every hour, or use a hot key to type the results directly into your text editor.
These powerful actions allow you to add any new facilities we have not provided for, stringing them together with other actions as desired.
You can also use the clipboard by piping from pbpaste and to pbcopy.
Shell scripts are executed in the background and can access variables by using environment variables, see the Variables section.
AppleScripts are executed in the background via osascript. This means they are not allowed to do user interaction. You can work around this by asking an application like System Events to do the user interaction for you, for example:
tell application "System Events" activate display dialog "Hello" end tell
AppleScripts can access variables by talking to the Keyboard Maestro Engine, see the Variables section.
File actions allow you to interact with the file system, moving, copying, duplicating, trashing or deleting files or folders. The actions are:
The source path must be an absolute path (or a home relative ~ path). The destination path must either be a simple single path component (not ~ or /) or an absolute path. If it is a simple path component, then it is relative to the parent directory of the source path. This is particularly useful in the Move or Rename action, as you can, for example, rename from ~/Folder/Old Name to New Name.
You can read or write files in a variety of formats, including PNG, TIFF, JPEG, as well as HTML, Web Archive, Word Document and more.
Image actions allow you to manipulate images, such as flipping, rotating, or capturing the screen. The actions are:
Image actions typically act on an image in the clipboard or in a named clipboard. You can read or write images files using the File actions.
Interface Control actions allow you to interact with the user interface, selecting menus, clicking buttons, simulating keystrokes and so forth. The actions are:
The various size and location fields can be Calculations.
The Select Menu Item action lets you choose from all currently running applications and their menus.
The Select Menu and Press Button actions allow you to specify multiple options separated by a vertical bar (eg Show|Hide) to allow for toggling menus. They will also ignore the difference between three dots (...) and an ellipsis so you do not have to worry which one the menu uses. Alternatively, you can start the name with an ^ and use a regular expression to match the menu or button name. Also, Select Menu will translate the word "APPLICATION" (all capitals) into the current application name, allowing menu selections like APPLICATION -> About APPLICATION.
The Select Menu and Press Button actions will, by default, abort the macro if the action is not successful (for example if the button or menu cannot be found or is disabled). The action can be configured to allow the macro to continue if the menu or button is not essential (such as “Mark As Read” which might be disabled if the item is already marked as read).
iTunes Control actions allow you to interact with iTunes, playing songs, stopping or pausing, rewinding or fast-forwarding. All actions will launch iTunes if it is not already running. The actions are:
Send a MIDI message:
The MIDI messages come from a device named “Keyboard Maestro” which will be created as soon as you add any MIDI action.
Keyboard Maestro can notify you in a variety of ways:
Open actions allow you to open files, folders, URLs or System Preference Panes. The actions are:
Files, folders, the Finder selection and URLs can all open either in their default applications, or a specific application. So you could, for example, create a macro that opens the Finder selection in BBEdit.
QuickTime Player Control actions allow you to interact with QuickTime Player, playing movies, stopping or pausing, stepping forward or backward, or adjusting the volume. All actions will launch QuickTime Player if it is not already running. The actions are:
Keyboard Maestro includes several powerful switchers, including Application Launcher, Application Switcher, Window Switcher, and Copy, Cut and Paste Clipboard Switchers and Clipboard History Switcher.
Each of these switchers is actually just a macro action, triggered like any other macro. By default Keyboard Maestro creates a Macro Group called Switcher Group which includes the following macros:
You can create your own macros using these actions or adjust their triggers within the Switcher Group.
By default, older versions of Keyboard Maestro used Option-Tab for its Application Switcher to avoid overriding the system Application Switcher, but if you wish to use Command-Tab you can do so. Similarly, if you wish to use the system switcher with Command-Tab, you can do so by changing the hot key trigger or by disabling Keyboard Maestro’s macro.
System Control allows you to control your Mac. Most are pretty self explanatory. The actions are:
The Insert Text action allows you to insert specified text either by setting the system clipboard and pasting, or by simulating a sequence of keystrokes. The Display Text action allows you to display the resulting text in a floating window or briefly in a HUD window (via Growl if available).
Tokens are provided to include variables, calculations, the time or date, or a large variety of other system information.
The Insert Text action can be very useful to insert standard text templates, such as your signature, address, copyright or other boilerplate text, and so on. If you ever get email from Peter, you will probably notice that many of his emails end with “Thanks for your kind words, Peter.” - with the amount of email he deals with, you don’t think he types that in every time do you?
Insert Text can expand various tokens, including dates in any ICU data format. For example, you can use an Insert Text action to insert the copyright message at the top of code files:
/* * Created by %UserName% on %ICUDateTime%EEE d MMM yyyy%. * Copyright (c) %ICUDateTime%yyyy% Stairways Software. All rights reserved. */
See also the Text Tokens section.
Keyboard Maestro includes permanently stored variables that you can use in a number of special purpose actions, as well as in Calculations or Text Tokens which can be used in almost any field in Keyboard Maestro.
These specific actions let you manipulate variables:
The Use Variable action can perform the following actions:
Most of these have analogs in the Text Tokens, so for example you might do:
Set variable ‘Temp’ To Text ‘%FrontWindowFrame%’ Set variable ‘Temp’ To Calculation ‘Temp[1]+Temp[3]/2,Temp[2]+Temp[4]/2’ Use ‘Temp’ to Set the Mouse Location
Which will result in the mouse being placed at the center of the front window.
Prompt For User Input will allow you to ask for user input, storing any results in variables as designed. If the variable is a password variable, it will be displayed in a password field.
If the default value you specify consists of choices separated by a bar (|), then a popup menu will be used (the first value will be the default value, and can be repeated later if a different location is desired). For example “Better|Good|Better|Best” would result in a popup menu with Good, Better, and Best, with Better pre-selected.
If the popup menu would contain only "0" and "1", then a checkbox is used (so for example “0|1" or "1|0", depending on the desired default).
You can include one or more buttons, which may optionally cancel the macro. You can also include /
See also the Variables, Text Tokens and Calculations sections.
This action displays a HUD window where you can enter a search query and then sends the query in your web browser. You can customize the URL (by default the query is to search Google).
Recording allows Keyboard Maestro to watch you as you perform a task and create the actions to produce a similar result.
Record Quick Macro is a variant of this that you can activate at any time without even launching Keyboard Maestro. You trigger the recording, and then perform a series of actions, and then turn off recording. Then press the associated hot key to replay the recording.
By default, Keyboard Maestro creates a macro triggered by Control-F1 which executes the Record Quick Macro action with a hot key of Option-F1. So for example, if you press Control-F1 to start quick recording, type “hello” and then press Control-F1 again to finish recording, then Keyboard Maestro will type “hello” each time you press Option-F1.
Because you cannot see or edit the recorded actions, it is best to keep them very simple. A good rule of thumb would be not to touch the mouse, just use the keyboard.
For example, say you wanted to quote a dozen different words in a paragraph, you could click in the middle of the first word, press Control-F1 to start quick recording, type Option-Left Arrow, quote ("), Option-Right Arrow, quote ("), and then Control-F1 again to finish recording. Now click in the middle of each remaining word and press Option-F1.
The Set Macro or Group Enable action allows you to enable, disable or toggle the enable of a macro group or macro. The Keyboard Maestro editor does not need to be running, but it will see the enable state when it is next launched (or immediately if it is already running).
The Comment action lets you store a comment in your Macro. It does nothing when executed. This can be useful for documenting complex macros.
These macros will show or hide the global macro palette. It will remain hidden until shown. You can also hide the global macro palette by clicking the close icon, so you may wish to include a global macro, perhaps with a status bar trigger, which uses the Show Macro Palette to redisplay it.