Keyboard Maestro IconKeyboard Maestro

Conduct your Mac Like a Pro!

Macro Actions


A Macro executes a sequence of Macro Actions in series. There are many actions to choose from (detailed below), some simple actions, for example Sleep Computer, require no other information and simply do their job, while other more complex actions, for example 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.

Process Control

Process Control actions allow your to switch, quit, or hide applications. The actions are:

Switch to Last Application
switches back to the previous application you were in.
Switch to Next Application
switches to the next application (as defined by the Program Switcher sorting method).
Activate Specific Application
launches if necessary and brings the specified application to the front.
Bring Application Windows Forward
brings the all the windows of the current application to the front.
Quit All Applications
quits all foreground applications, optionally honoring the excluded application list.
Quit Other Applications
quits all foreground applications except the current one, optionally honoring the excluded application list.
Quit Specific Application
quits the specified application.
Hide All Applications
hides all foreground applications, optionally honoring the excluded application list.
Hide Other Applications
hides all foreground applications except the current one, optionally honoring the excluded application list.
Hide Current Application
hides the current application.

Interface Control

Interface Control actions allow you to interact with the user interface, selecting menus, clicking buttons, simulating keystrokes and so forth. The actions are:

Manipulate Window
resize, move, center, bring to front, close, zoom, or minimize the front window or a specified window.
Move or Click Mouse
move, click or move and click the mouse. You can specify modifiers such as the shift key, as well as the position, relative to any corner of the front window, the main screen, or the current mouse location.
Select Menu Item
select a specified menu item in the front or a specified application.
Press Button
press a named button in the front window.
Simulate Keystroke
simulate pressing a specified keystroke.
Simulate Scroll Wheel
simulate scrolling the mouse wheel up or down, left or right.

iTunes Control

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:

Play Titled Song
play a specified song.
Play Titled Playlist
play the songs in a specified Playlist.
Play Random Song From Library
play a random song.
Play Random Song From Titled Playlist
play a random song from a specified Playlist.
toggle from playing to pausing or vice-versa.
pause the current song.
stop playing any song.
fast-forward the current song. It will keep fast-forwarding until you do something else or until it reaches the end of the song.
rewind the current song. It will keep rewinding until you do something else or until it reaches the beginning of the song.
Next Song
play the next song.
Previous Song
Go to the previous song or the start of the current song if it is already playing.
Increase/Decrease Volume
Increase or decrease the iTunes volume.

System Control

System Control allows you to control your Mac. Most are pretty self explanatory. The actions are:

Sleep Computer
puts your Mac to sleep.
Restart Computer
restarts your Mac.
Shutdown Computer
shuts your Mac down.
Log Out
Log Out the current user.
Activate Screen Saver
starts the screen saver (could be especially useful if the screen saver requires a password to unlock it).
Open/Close CD Tray
Opens the CD tray if it is closed, or closes it if open (especially useful for keyboards that do not have an eject key).
Toggle System Sound Mute
Mutes the sound if sound is currently on, unmutes the sound if already muted.
Increase/Decrease System Sound Volume
Increases or decreases the sound volume.
System Beep
Play a simple beep (this can be useful for debugging complex Macros).
Increase/Decrease Screen Brightness
Increases or decreases the screen brightness.


Open actions allow you to open files, folders, URLs or System Preference Panes. The actions are:

Open File or Folder
opens a specified file or folder. Don’t underestimate the power of this command as you can open bookmarks or other action documents to perform a lot of customized actions.
Open URL
open a URL with the appropriate helper.
Open System Preference Pane
opens a specified System Preference Pane.


Execute actions let you execute AppleScripts, Unix scripts or Automator Workflows. Unix scripts can be any kind of script, sh, zsh, tcsh, perl, python, and so on. The actions are:

Execute AppleScript
execute a specified AppleScript, either from a file or text. For example, “say "hello"”.
Execute Unix Script
execute a specified Unix script, either from a file or text. For example, “pbpaste | pbcopy”.
Execute Automator Workflow
execute a specified Automator Workflow.

If the AppleScript or Unix script generates any results, they can be optionally displayed in a floating window or briefly ina HUD window. For example, you could have a unix script date display briefly in a HUD window every hour.

These powerful actions allow you to add any new facilities we have not provided for, stringing them together with other actions as desired.


Clipboard actions let you manipulate the system clipboard, Named Clipboards and cut, copy or paste clipboard items. The actions are:

Copy, Paste,simulate command-X, command-C, or command-V keystrokes to Cut, Copy or Paste to/from the system clipboard.
Insert Text
insert the specified text. Tokens are provided to include such things as the time or date. Text can be inserted by setting the system clipboard and pasting, or by simulating a sequence of keystrokes.
Use Named Clipboard
cut, copy or paste to/from the specified Named Clipboard.
Set Clipboard to Text
set the system clipboard to text. Tokens are provided to include such things as the time or date.
Set Clipboard to Past Clipboard
set the system clipboard to some item that was previously copied to the system clipboard. This can be used to restore the system clipboard after another action sets the clipboard temporarily.
Set Clipboard to Named Clipboard
set the system clipboard to a specified Named Clipboard.
Save Clipboard to Named Clipboard
set the specified Named Clipboard to the current system clipboard.
Apply BBEdit Text Factory
apply any saved BBEdit Text Factory to the current system clipboard.
Filter Clipboard
apply one of a set of filters on the current system clipboard (see below for a list).

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 “Enjoy, 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 date format. For example, we 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.

Filter Clipboard can apply a number of possible transforms to the currect system clipboard:

We will likely expand the list of possible filters, so if you have specific filtering needs that you think might be of general inbterest, please let us know. Alternatively, in the mean time, remember that you can apply scripted filters using a unix or AppleScript, for example the unix 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.

Activate Switcher

Keyboard Maestro includes several powerful switchers, including Program 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:

Clipboard Switcher Copy
copies the current selection to a selected named clipboard (command-shift-C).
Clipboard Switcher Cut
cuts the current selection to a selected named clipboard (command-shift-X).
Clipboard Switcher Paste
pastes the selected named clipboard into the current system clipboard and current selection (command-shift-V).
Clipboard History Switcher
pastes a previous system clipboard from the clipboard history into the current system clipboard and current selection (command-control-shift-V).
Program Switcher
activates the Program Switcher (option-Tab).
Window Switcher
activates the Window Switcher (control-Tab).

You can create your own macros using these actions or adjust their triggers within the Switcher Group.

Unfortunately, the system program switcher uses command-Tab with no way to disable it, so that hot key is not available for your use, which is kind of ironic since Keyboard Maestro and its predecessor, Program Switcher, were providing this functionality long before it was available as part of the system software. A recent bug report to Apple on this resulted in the not-very-promising response of “At this point, though, Engineering believes the issue behaves as intended.”.

Record Quick Macro

Recording is a new facility introduced in Keyboard Maestro 3. It 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 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 Pause action lets you pause in the middle of a sequence of actions. You can use this to get a visual break in your sequence of actions (eg for a slideshow), or to allow time for the applications affected by previous actions to "catch up" before continuing.

Continue on to Macro Triggers


Feedback Form

Please provide any feedback you may have

Email Address:

Your email address is appreciated but is not required and will not be saved.
It will be used only for responding to or clarifying this feedback.


Keyboard Maestro

Old Documentation