Keyboard Maestro 2 Documentation

Overview

Keyboard Maestro will take your Macintosh experience to a new level in “Ease of Use”. With Keyboard Maestro you can design your own macro shortcuts and activate them at any time, you can navigate through running applications and open windows with Program Switcher, and you can work with an unlimited number of clipboards - all by pressing simple keystrokes.

Keyboard Maestro consists of three functions, each focusing on a particular need.

Using Keyboard Maestro’s powerful Macros, you can control applications, windows, or menus; insert text; open documents, applications or URLs; execute scripts; control the system, iTunes, or a PowerMate; and more, all with the touch of a key, click of the mouse, periodically or at specific times, or even when an application is launched or running.

Using Keyboard Maestro’s Program Switcher, you can cycle through applications or windows, closing, hiding, launching, and more. Keyboard Maestro can help you regain control of your crowded screen by letting you close or hide multiple windows or applications.

Using Keyboard Maestro’s Clipboard Switcher, you can select from a number of named clipboards, storing information away for later retrieval. Store the details you are working on and access them by name again and again.

You may try Keyboard Maestro for a few weeks, but then you must purchase a license to continue using it.

What’s New

Keyboard Maestro 2 was acquired by Stairways Software on 30 June 2004 and we have continued to build on the solid foundations that Michael Kamprath developed in Keyboard Maestro 1 and the initial 2.0 betas.

Keyboard Maestro 2 represents a complete rewrite of the internal engine to support multiple Macro Triggers including:

Keyboard Maestro 2 also adds support for a wealth of new actions, including:

Keyboard Maestro 2 adds a new concept of a Macro Group, a set of Macros that are enabled for a specific application (or applications). This allows you to easily create Macros to enhance a particular application without tying up Hot Keys in other applications or reuse a Hot Key in different applications to get different behaviors.

Keyboard Maestro 2 adds support for importing and exporting Macros so you can share Macros with your friends and colleagues.

Detailed changes follow.

New in 2.1.3

New in 2.1.2

New in 2.1.1

New in 2.1

New in 2.0.3

New in 2.0.2

New in 2.0.1

New in 2.0

Features

Keyboard Maestro 2 is a productivity enhancer with three main functions, allowing you to design your own macro shortcuts and activate them at any time, navigate through running applications and open windows with Program Switcher, and work with an unlimited number of clipboards using Clipboard Switcher.

Macros

Program Switcher

Clipboard Switcher

Purchase

Keyboard Maestro is engineered by Stairways Software Pty Ltd and distributed by Kagi. Keyboard Maestro is licensed on a per workstation basis (individuals can choose to license it on a per user basis).

New customers can purchase Keyboard Maestro for US$20 by choosing Purchase from the Keyboard Maestro menu or you can purchase multiple licenses from http://store.stairways.com/.

Keyboard Maestro 2 is a paid upgrade from previous versions. Customers who purchased Keyboard Maestro 1 after 1 July 2004 from Stairways Software have been issued a free upgrade to Keyboard Maestro 2. If you have not received it, you can claim your free upgrade by looking up your Keyboard Maestro 1 purchase at http://enquiry.stairways.com/.

Customers who purchased Keyboard Maestro 1 from Michael Kamprath before July 2004 will be able to upgrade to Keyboard Maestro 2 for US$10. In order to qualify for the discounted upgrade, you must have transferred your Keyboard Maestro 1 details to Stairways Software (you should have received information on doing this around mid-August). If you have not yet done so, please contact us and we will liaise with Michael about the transfer. Once your details have been transferred, you can claim your discounted upgrade to version 2 by looking up your license at http://enquiry.stairways.com/.

Note: Customers who have transferred their details to Stairways and who have elected to receive update emails have been emailed with new license or upgrade instructions as appropriate. If you have not received your upgrade license or purchase instructions, let us know and we will look into why you did not receive your email.

It is our informal policy to have a paid major upgrade roughly once a year. This allows us to have a reasonably consistent revenue stream with which to fund development of Keyboard Maestro.

A fully-functional trial version of Keyboard Maestro is available for downloaded from http://download.stairways.com/.

For sales enquires, customer service, technical support, or to contact project management, our current contact information is listed at http://contact.stairways.com/.

For more information about anything to do with Keyboard Maestro visit http://www.keyboardmaestro.com/.

Screenshots

This is a very quick taste of Keyboard Maestro.

Macro Window Pane

Macros Window Pane

Macro Editor Window

Macro Editor Window

Program Switcher Window

Program Switcher Window

Window Switcher Window

Window Switcher Window

Clipboard Switcher Window

Clipboard Switcher Window

Tour

This demonstration will give you some idea of the power and versatility of Keyboard Maestro.

Getting Started

To start, launch Keyboard Maestro and it will display the Macros window pane.

Macros Window Pane

You can see some example Macros we have included for you.

Make New Macro

Click the New Macro button to display the Macro Editor window. We will now design quite a complex Macro that will allow you to save clippings to a text file. First, launch TextEdit and create a new empty document and save it to Clippings.rtf in your Documents folder.

Now to add a selection to the Clippings file, you would normally do this:

That is all very tedious, and probably explains why you do not bother doing it!

So lets define the whole sequence as a Macro.

Macro Editor Window

Now switch to the Trigger pane and define a Hot Key, say F2 (by default, F1 is defined to play a random song in iTunes, so you will have to disable that if you want to use F1).

Macro Editor Window

Save the Macro and now any time you have some text you want to save, just select it and press F2!

Named Clipboards

If you were paying attention, you might have noticed that rather than just copy the selection using Command-C, we actually copied it to the named clipboard “Clipping”. Keyboard Maestro lets you create as many named clipboards as you want using the Clipboard Switcher window pane.

Clipboard Switcher Window Pane

and then you can cut, copy or paste from them using the defined Hot Keys (by default, Command-Shift X, C and V respectively).

Clipboard Switcher Window

You can save frequently used information like your copy logo in named clipboards and then paste them whenever you want, or use a named clipboard to store current information, like the current customer or project and paste it in as required.

Program Switcher

At the end of the Macro we defined, we used the Switch To Last Application action to switch back to the program you were using before. Of course, most people use a lot more than one program and need to be able to switch between them. Keyboard Maestro not only lets you switch between applications, but also lets you define Fast Launch Applications applications that always appear when you are switching so you can launch them quickly, and also Excluded Applications that never appear. As well, you can quit, hide or show applications. You can configure the Program Switcher in the Program Switcher window pane.

Program Switcher Window Pane

By holding down the Program Switcher modifier and pressing the activation key (for example, Option-Tab), the Program Switcher window appears.

Program Switcher Window

Note the applications set to be launched or quit. If you want to be able to launch a specific program with a key press, you can define a Macro to do that and assign a Hot Key Macro Trigger such as F3.

By holding down the Window Switcher modifier and pressing the activation key (for example, Control-Tab), the Window Switcher window appears showing the windows in the current application.

Window Switcher Window

Note the windows set to be closed. This is a very useful way of cleaning up an application with a lot of open windows, especially prevalent in the Finder.

Conduct Your Mac Like a Pro!

This is just a taste of what Keyboard Maestro can do for you. Isn’t it time you started getting the most from your Mac? Download Keyboard Maestro today and you can be working faster and smarter in no time.

Links

Keyboard Maestro can be downloaded from http://download.stairways.com/.

You can purchase Keyboard Maestro at http://store.stairways.com/.

You can look up your current or previous license status and serial numbers, and get information about discounted upgrades from http://enquiry.stairways.com/. If you purchases Keyboard Maestro 1 before June 30 from Michael Kamprath then you will be eligible for a discounted upgrade to Keyboard Maestro 2 when it is released if you have transferred your license details to Stairways Software (you should have received an email from Michael with instructions on how to do that, if not, please contact us and we will assist you).

You can join the Keyboard Maestro User Group online community consisting of the developers and users of Keyboard Maestro at http://user.keyboardmaestro.com/.

Documentation describing Keyboard Maestro is available at http://documentation.keyboardmaestro.com/.

For sales enquires, customer service, technical support, or to contact project management, our current contact information is listed at http://contact.stairways.com/.

For more information about anything to do with Keyboard Maestro visit http://www.keyboardmaestro.com/.

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). Remember to hold the option key down while copying, otherwise the Finder may simply make an alias to the disk image volume.

When you launch Keyboard Maestro it installs an invisible “Keyboard Maestro Engine” that continues to run even after you quit Keyboard Maestro. The engine is the process that enables your Macros, Program Switcher, and Clipboard 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 Keyboard Maestro preference “Launch Engine at Login” 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?

To upgrade Keyboard Maestro, simply replace the Keyboard Maestro application in your Applications folder with the new one. Because the Keyboard Maestro Engine is probably running, the Finder may not let you replace the existing application with the new version, so either launch Keyboard Maestro and choose Quit Engine from the File menu to quit the engine, or trash the existing application, copy the new Keyboard Maestro application, and the launch the new version (it will automatically quit the old engine and start the new one). Then you can empty the Trash.

If you have not done so already, you should consider turning on the Keyboard Maestro preference “Launch Engine at Login” to ensure all of Keyboard Maestro’s facilities are available to you as soon as you login or startup your Mac.

If you are upgrading from Keyboard Maestro 1, you no longer need to have the application as a startup item, Keyboard Maestro 2 will add the Keyboard Maestro Engine as a startup item for you if you enable the “Launch Engine at Login” preference.

How do I purchase Keyboard Maestro?

New customers can purchase Keyboard Maestro for US$20 by choosing Purchase from the Keyboard Maestro menu or you can purchase multiple licenses from http://store.stairways.com/.

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

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

See also the Purchase section.

How do I register Keyboard Maestro?

If you purchase Keyboard Maestro from within Keyboard Maestro by choosing Purchase from the Keyboard Maestro menu, it will automatically be registered.

Regardless of how you purchase Keyboard Maestro you will immediately 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 (we recommend creating a folder in your Email client and saving all your serial number emails there).

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 Kagi (click the Track Order link) or at http://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 2 and either immediately click the Use Existing License button or choose Register from the Keyboard Maestro menu. Now 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 is exactly as shown (the serial number’s email address does not change even if you have changed your email address with us or Kagi).

How do I get started?

The easiest way to get started is to use your Mac normally and keep an eye open for things you do repetitively. Things like:

When you notice something, consider making a Macro to do it and assigning it to a Hot Key. 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.

See also the Tips section.

How do I create a new Macro?

To create a Macro, launch Keyboard Maestro, select the Macros window pane and click the New Macro button. Give the Macro a name, select at least one action and at least one trigger and click the Save button. The Macro is immediately active.

How do I Insert Styled/Colored Text or Images?

You can insert plain text using the Clipboard -> Insert Text action. If you want to insert styled text or images you can do so using a named clipboard. Here is how to create a Macro to insert styled text when you press a Hot Key (the same method would work for an image with minor changes).

How do I uninstall Keyboard Maestro?

Launch Keyboard Maestro and ensure the “Launch Engine at Login” preference 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.

Macros

Overview

Macros, also known as Shortcuts, are a way of improving your productivity by allowing you to more quickly perform repetitive or frequently required actions, tailoring your Mac to your usage patterns. Each macro consists of a sequence of Macro Actions to be performed together with one or more possible Macro Triggers which define when the actions will be performed. Sets of Macros are collected together in to Macro Groups.

Macro Groups

A Macro Group contains a set of Macros. The Macros in each Macro Group can be restricted to only a defined set of applications, so you can target particular Macros to particular applications and use the same Macro Triggers (often Hot Keys) in different applications to perform different actions.

To create a new Macro Group, first launch Keyboard Maestro and click the Macros tab to select the Macros window pane.

Macros Window Pane

Now click the New Macro Group button. Enter the name of your new Macro Group, select the targeting from the pop-up menu, one of:

The first choice, All Applications, will allow you to define Macros that are always active. These are especially useful for Macros that give you instant access to applications or documents . For example you might have a Macro to launch your email client or word processor, or a Macro to open your financial accounts (perhaps one Macro to open your personal accounts and another to open your business accounts).

The second choice, Only These Applications, lets you specify which particular applications these Macros should apply to. Often you will select just a single application and define Macros for you to use while working in that particular application. For example, you might make a Macro to execute a series of menu commands, enter template text, or open a glossary document.

The third choice, All But These Applications, lets you disable Macros in particular applications. For example, you might want to disable your global Macros in a game or in a complex application where you needed to use many native function keys to use the program but wanted to use your function keys for other purposes normally.

The last choice, No Where (Inactive), allows you to create a Macro Group for disabled Macros. You could use this to store Macros you are not currently using, or to you could temporarily disable a Macro Group by switching it to “No Where (Inactive)”.

You can change the targeting of an existing group by double clicking on it in the Macros window pane.

To delete a Macro Group, first delete all the Macros it contains (or move them to other Macro Groups), and then select the group and press the Delete key.

You cannot delete or rename the Global Macro Group.

Macros

A Macro consists of a sequence of Macro Actions to be performed together with one or more possible Macro Triggers which define when the actions will be performed. A typical Macro consists of a single action, such as "open a particular file" together with a single Hot Key trigger, such as "control-F1".

To create a Macro, first launch Keyboard Maestro and select the Macros window pane and then click the New Macro button. The Macro Editor window will be displayed.

Enter the name of your new Macro (you can skip this and it will be named for you based on the action you select).

Now select a new action from the New Action pop-up menu. There are many Macro Actions to choose from. The actions you include will be executed in order. You can reorder the actions by dragging them around.

Now select a new trigger by switching to the Triggers pane and choosing it from the New Trigger pop-up menu. There are many Macro Triggers to choose from, the most common being the Hot Key which allows you to execute the Macro at the press of a key. You can define several different triggers and any of the triggers will execute the Macro Actions.

Finally click the Save button to save the Macro. It will be available immediately (subject to the restrictions of the Macro Group it is contained in). By default, new Macros will be created in the Global Macro Group, but if you select a Macro Group before clicking the New Macro button, the Macro will be created within that group.

You can delete any extra actions or triggers by selecting them and pressing the Delete key or by dragging them to the Trash.

See also the Macro Groups, Macro Actions and Macro Triggers sections.

Macro Actions

Overview

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.
Quit Other Applications
hides all foreground applications except the current one, optionally honoring the excluded application list.
Hide Specific Application
hides the specified application.

Interface Control

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

Manipulate Window
resize, move, 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 specified button in the front window.
Simulate Key Press
simulate pressing a specified keystroke.
Simulate Scroll Wheel
simulate scrolling the mouse wheel up or down.

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.
Play/Pause
toggle from playing to pausing or vice-versa.
Pause
pause the current song.
Stop
stop playing any song.
Fast-Forward
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
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.

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.
Shutdown Computer
shuts your Mac down.
Restart Computer
restarts your Mac.
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 System Sound Volume
Increases the sound volume.
Decrease System Sound Volume
Decrease the sound volume.
System Beep
Play a simple beep (this can be useful for debugging complex Macros).
Increase Screen Brightness
Increase the screen brightness.
Decrease Screen Brightness
Decrease the screen brightness.

Open

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

Execute actions let you execute AppleScripts or Unix scripts. Unix scripts can be any kind of script, sh, zsh, tcsh, perl, python, and so on. If the script generates any results, they are displayed in a floating window. The actions are:

Execute AppleScript
execute a specified AppleScript.
Execute Unix Script
execute a specified Unix script.

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

Clipboard

Clipboard actions let you insert text (the text is placed in the clipboard, pasted in, and then the clipboard restored) or use a named clipboard. The actions are:

Insert Text
insert the specified text. Tokens are provided to include such things as the time or date.
Use Named Clipboard
use the specified clipboard.

The Insert Text action can be very useful to insert standard text templates, such as your signature, address, 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?

PowerMate Control

The PowerMate Control action let you control the brightness and pulsing of the PowerMate. You can specify the brightness, pulsing speed, and whether pulsing continues during sleep.

Pause

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.

Macro Triggers

Overview

A Macro is executed when any of its Macro Triggers is activated. There are many triggers to choose from (detailed below), the most common being a Hot key, that is a Macro is executed in response to a key press, usually in conjunction with one or more modifier keys. You can also create a floating palette of macros, execute macros in response to applications launching or quitting, or continuously while they are running, execute macros using a PowerMate, or at a particular time of day, as well as other possible events.

There are many Macro Triggers available for your use.

Hot Keys

The most common Macro Trigger is the traditional Hot Key. You execute a Macro by pressing a key combination - a keyboard key like a letter, number, symbol or function key in combination with one or more modifiers (Shift, Control, Option and/or Command). Except for function keys, you must specify at least one modifier. Normally the Macro will not repeat if you hold the key down, but you can enable Key Repeat to have the macro execute continuously while you hold they key combination down.

A common use for Hot Key triggers is to open applications or documents, insert text templates, or as a way of remapping command keys (for instance you can make command-T execute “Replace and Find Again” in an application that uses a different command key (or no command key) for that menu command).

Application

You can have a Macro execute in response to an application event, such as when the specified application launches, quits, activates or deactivates. You can also have the Macro run periodically while an application is running or while it is at the front.

You could use a trigger like this to simulate workspaces by automatically setting up an application the way you want when you launch it, or you could clean up after an application when you quit.

Time

You can use the Time trigger to execute a macro when you login or at a specific time. You can also execute a macro periodically (for example every ten minutes or every three days). Time triggers can also be restricted to certain days of the week.

You could use a trigger like this to set up your Mac environment before arriving at work, run periodic maintenance or backup scrips late on the weekend, or launch iChat for your weekly video conference.

Macro Palette

You can have a macro execute when you click on it in a floating Macro Palette. Keyboard Maestro will only display the palette when there are active Macros, so if your Macros are restricted to particular applications, then the Macro Palette will only appear in those applications.

You could use a trigger like this to add an action palette to an application that does not have such a facility.

PowerMate

You can have a macro execute when you use a PowerMate, clicking or turning the knob, optionally in conjunction with a modifier key. If you have a PowerMate, this is a way of letting it access all the power of Keyboard Maestro.

Macro Examples

Here are a number of example and suggestions for Macros to give you some ideas of how you can get the most out of Keyboard Maestro and your Mac. For tips on how to remember which Hot Key executes which action, see the Remembering Macro Hot Keys section.

Launch Your Most Used Applications

Use function keys to launch or switch to your most used applications. For example, you probably often switch to the Finder, your Email client, your Web Browser, your Word Processor. Consider putting these and other frequently used applications on function keys.

Open Your Most Used Documents

Use control-function keys to open your most used documents. For example, you might have a documentation file or financial details file that you access frequently, consider putting these on control-function keys.

Insert Text Templates

Use control-letter keys and the Insert Text action to type in text for you, such as your name, address, phone number, and so on. Consider restricting these to just the appropriate applications like your Email client or Word Processor by creating a Macro Group for them.

Use Hot Keys to Open Financial Accounts

If you keep your finances on your computer, then you probably need to open a document every time you enter a bill or receive a statement. By creating a Hot Key to open the document for you, you can save a few seconds every time - at least it might make receiving a bill slightly less unpleasant! If you have multiple accounts (eg personal, business, association) then this can be even more useful.

Use Hot Keys to connect to SSH or FTP sites.

You could use Hot Keys to connect to your common servers. You might need to create a Bookmark file for the site and use the Open File Macro Action.

Simulate Bookmarks

You could Use Hot Keys to Insert Text, Simulate Tab Press, Insert Text, Simulate Return Press to make effective bookmarks for applications that do not have an inbuilt bookmark system or to enter form data. While you could use this to enter usernames and passwords I would advise you use a tool like Web Confidential for such things as it will provide secure storage for your password.

Remap Command Keys

If you find yourself pressing a command key in an application and expecting it to do something but it does not work (for example, command-T for “Replace and Find Again”), use a Macro to make the command key “do the right thing” in that application. Similarly, if you use a function in an application frequently, but it has a convoluted command key or no command key at all, define your own command key by using a Hot Key to select the menu item.

Simulate Missing Features

If you find yourself missing a feature in one application that you are used to in another application (perhaps you switched email clients and a feature is missing), see if you can simulate the feature with a sequence of commands and then use a Hot Key for that. For example, Close Window, Down Arrow, Return to move to next email message.

Swap Characters

If you often type characters out of order, use a Hot Key to swap them by first placing the cursor between them and then executing:

Save a Text Clipping

If you often want to save snippets of text, you could create a Hot Key to save a clipping:

Setup an Application When Launched

If you always do a set of things every time you launch an application (eg arrange the windows in a particular way), use an application Macro Trigger to execute a Macro when you launch the application, then have the Macro do the work for you.

Clean Up After Using an Application

If you always do something after quitting an application (eg unmount a server or disconnect from the Internet), use an application Macro Trigger to execute a Macro when you quit the application. You might need to do a little AppleScripting to perform the action and then use the Execute AppleScript action.

Feedback During Macro Execution

A Macro can play a System Beep when it is executed, but if you want to do something more, you can use an AppleScript or Unix script to play a sound (perhaps using the free utility Play Sound, AppleScript tell application "PlaySound" to play file "..."), speak text (AppleScript say "hello") or display an alert (AppleScript display dialog "hello").

By adding sound effects to your Macro sequences you can give clear feedback as to what is happening.

Program Switcher

Program Switcher is essentially a highly specialized Hot Key that enables you to launch, switch, hide, and quit applications with one keystroke. By pressing a single keystroke, Program Switcher enables you to switch between all running applications or all current windows. Once the switching window appears, you may select the application or window to activate, and Program Switcher will take you to it.

Configuring Program and Window Switcher

To configure Program and Window Switcher, first launch Keyboard Maestro and click the Program Switcher tab to select the Program Switcher window pane.

Program Switcher Window Pane

In the Program Switcher window pane you can:

You can have Program Switcher hide other applications when you switch using Program Switcher, or hide other application always, no matter how you switch. By default Program Switcher will not hide other applications. Applications on the excluded application list (see the Preferences section) will not be hidden.

Program and Window Switcher Keystroke

You select a pair of keys that you can press to activate the application or window switching feature. This sequence defaults to Option and Tab for application switching and Control and Tab for window switching, but may be configured in the Program Switcher window pane. When pressing this keystroke, be sure that you hold down the modifier key (the Option, Control, or Command key) prior to pressing the switching key (the Tab, Tilde (~), Back Slash (\), or Space key).

Program and Window Switcher Window

Once activated, the switching window appears listing all the applications or windows and remains until you release the modifier key. You can navigate by pressing the switching key (usually Tab) or the arrow keys. You can cancel the window by pressing the Escape key. When you release the modifier key, Program Switcher will bring the selected application or window to the front. While the window is open, you can use the following keys (configurable in the Program Switcher window pane) to access extra functionality:

Q
mark the application to be quit or window to be closed.
Z
mark the application to be launched.
S
mark the application to be hidden or window to be minimized.
F
selects the Finder.
A
toggle the display of launchable applications.
E
toggle the display of excluded applications.

Clipboard Switcher

Clipboard Switcher enables you to define any number of named clipboards which can be use to Cut or Copy into and Paste from in any application. To use Clipboard Switcher, you simply press the configurable keystrokes for Clipboard Switcher’s Copy, Cut, and Paste actions. Clipboard Switcher will present you with a window allowing you to select the clipboard to use.

Configuring Clipboard Switcher

To configure Clipboard Switcher, first launch Keyboard Maestro and click the Clipboard Switcher tab to select the Clipboard Switcher window pane.

Clipboard Switcher Window Pane

In the Clipboard Switcher window pane you can:

Preferences

To configure Keyboard Maestro, first launch Keyboard Maestro and click the Preferences tab to select the Preferences window pane.

Preferences Window Pane

In the Preferences window pane you can:

Windows

Macros Window Pane

This window pane lets you manipulate Macros and Macro Groups, creating new ones, deleting old ones, enabling and disabling them and so on.

You get this window pane by launching Keyboard Maestro and clicking the Macros tab.

Macros Window Pane

The window pane contains a list of Macro Groups and their associated Macros.

You can create a new Macro Group by clicking the New Macro Group button. A sheet will appear allowing you to enter the name of the group and choose the applications in which the group’s Macros should be active. Typically a group’s Macros would be active everywhere (All Applications), or it might be specific to a particular application (Only these Applications) in which case you might name the Macro Group after the application.

You can create a new Macro by clicking the New Macro button. A Macro Editor window will appear and allow you to define your new Macro. The new Macro will be created in the same Macro Group as you currently have selected, or the Global Macro Group if no item is selected.

You can rename or change an entry (Macro or Macro Group) by double clicking it, or delete it by selecting it and pressing the Delete key. You can only delete empty Macro Groups and you cannot delete or rename the Global Macro Group.

See also the Macros and Macro Editor Window sections.

Macro Editor Window

This window lets you edit or create a Macro.

You get this window by clicking by selecting the Macros window pane and either clicking the New Macro button to create a new Macro or by double clicking an existing Macro to edit it.

Macro Editor Window

You can give the Macro a name, add, delete or rearrange actions, and add or delete triggers.

To learn more about creating or editing Macros, see the Macros section.

Program Switcher Window Pane

This window pane lets you configure Program and Window Switcher.

You get this window pane by launching Keyboard Maestro and clicking the Program Switcher tab.

Program Switcher Window Pane

To learn more about the Program and Window Switcher, see the Program Switcher section.

Program Switcher Window

This window lets you switch between active programs, as well as quit or hide programs or quickly launch frequently used programs.

You get this window by pressing the Program Switcher Keystroke at any time in any application (as long as the Program Switcher is active and the Keyboard Maestro Engine is running).

Program Switcher Window

To learn more about the Program Switcher, see the Program Switcher section.

Window Switcher Window

This window lets you switch between windows in the current application, as well as close or minimize windows.

You get this window by pressing the Window Switcher Keystroke at any time in any application (as long as the Window Switcher is active and the Keyboard Maestro Engine is running).

Window Switcher Window

To learn more about the Window Switcher, see the Program Switcher section.

Clipboard Switcher Window Pane

This window pane lets you configure Clipboard Switcher.

You get this window pane by launching Keyboard Maestro and clicking the Clipboard Switcher tab.

Clipboard Switcher Window Pane

To learn more about the Clipboard Switcher, see the Clipboard Switcher section.

Clipboard Switcher Window

This window lets you select between named clipboards to copy or paste from.

You get this window by pressing one of the Clipboard Switcher Keystrokes (one each for Cut, Copy and Paste) at any time in any application (as long as the Clipboard Switcher is active and the Keyboard Maestro Engine is running).

Clipboard Switcher Window

To learn more about the Window Switcher, see the Clipboard Switcher section.

Preferences Window Pane

This window pane lets you configure Keyboard Maestro.

You get this window pane by launching Keyboard Maestro and clicking the Preferences tab.

Preferences Window Pane

To learn more about the Preferences, see the Preferences section.

About Window Pane

This window shows you the version of this copy of Keyboard Maestro, to whom it is registered, and allows you to visit the web site.

You get this window by launching Keyboard Maestro and clicking the About tab.

About Window Pane

Menus

The Keyboard Maestro menu contains menu items relating to the Keyboard Maestro application as a whole.

The About Keyboard Maestro command in the Keyboard Maestro menu displays the About Keyboard Maestro window.

The Purchase command in the Keyboard Maestro menu lets you purchase Keyboard Maestro online.

The Register command in the Keyboard Maestro menu displays the serial number entry window allowing you to enter your username (email address) and serial number. Make sure you enter them exactly as sent to you.

The Preferences command in the Keyboard Maestro menu displays the Preferences window.

The Services command in the Keyboard Maestro menu is used to perform Mac OS X Services which are shared functions available across multiple applications. You can learn more about Mac OS X Services from your Mac OS X documentation, and you can install new services which will work with Keyboard Maestro. Keyboard Maestro includes full support for Services, so relevant Services on your system are available in Keyboard Maestro.

The Hide Keyboard Maestro command in the Keyboard Maestro menu will hide the Keyboard Maestro application and all its windows. Click on Keyboard Maestro's Dock icon or choose Show All to show Keyboard Maestro again.

The Hide Others command in the Keyboard Maestro menu will hide all other applications. Choose Show All to show them again.

The Show All command in the Keyboard Maestro menu will show all hidden applications.

The Quit Keyboard Maestro command in the Keyboard Maestro menu will Quit Keyboard Maestro. the Keyboard Maestro Engine will remain running and all enabled Keyboard Maestro features will continue to operate (unless you have specifically quit the Keyboard Maestro Engine).

The File menu is where you import or export Macros or launch or quit the Keyboard Maestro Engine.

The Close Window command in the File menu closes the front window.

The Export Macros command in the File menu exports the selected macros to a file that you can share with others. If you create any interesting macros, please consider sending them to us and we will make them available on our web site.

The Import Macros command in the File menu lets you select a saved macro file and imports the macros it contains.

The Quit Engine command in the File menu lets you quit the Keyboard Maestro Engine. The Keyboard Maestro Engine performs all the Macro, Program Switcher and Clipboard Switcher functions even while Keyboard Maestro itself is not running. It is launched automatically as a Startup Item when you login (assuming you have not disabled that in the Preferences window). If you quit the Keyboard Maestro Engine these functions will no longer operate. This menu item only exists while the Keyboard Maestro Engine is running.

The Launch Engine command in the File menu lets you start the Keyboard Maestro Engine manually. The Keyboard Maestro Engine performs all the Macro, Program Switcher and Clipboard Switcher functions even while Keyboard Maestro itself is not running. It is launched automatically as a Startup Item when you login (assuming you have not disabled that in the Preferences window). If it is not running for any reason you can start it manually with this command. This menu item only exists while the Keyboard Maestro Engine is not running.

The Edit menu contains menu items relating to text and selections.

The Undo command in the Edit menu undoes the previous command. Most operations in Keyboard Maestro cannot be undone, so use caution.

The Redo command in the Edit menu redoes the previous undone command. Most operations in Keyboard Maestro cannot be undone, so use caution.

The Cut command in the Edit menu copies the current selection to the clipboard and then deletes the selection.

The Copy command in the Edit menu copies the current selection to the clipboard.

The Paste command in the Edit menu pastes the clipboard into the current selection.

The Clear command in the Edit menu deletes the current selection.

The Select All command in the Edit menu selects all text or items.

The Help menu contains menu items relating to Help.

The Keyboard Maestro Help command in the Help menu takes you to Help Viewer and displays the Keyboard Maestro local documentation.

Tips

Remembering Macro Hot Keys

Hot Key Macros are only useful if you can remember which key does what.

Consider using mnemonic Macros. For example, in your email client, you might define a set of Macros to Insert Text, so use control-A for your Address, control-S for your Signature, control-N for your Name, and so on.

For function keys, consider either putting a label on your keyboard above the function keys. We've found you can use a fine felt tipped pen to write on your keyboard directly (usually this will come off easily with a wet finger, but avoid any permanent markers that you might regret later!).

Be consistent in your choice of Hot Keys. For example, use function keys to launch applications, control-function keys to open documents, control-letter to Insert Text, and so on.

Use Function Keys for Global Hot Keys

It is quite hard to come up with global Hot Keys that will not conflict with those keys used by any application (a conflict is not really a problem, the Macro Hot Key will simply override the application, but this is not always desirable). It is best to use function keys, especially in conjunction with modifiers, as global Hot Keys since they tend not to be used by most applications.

Troubleshooting

Macros/Switching does not work after I login, what’s wrong?

The Macros/Switching was all working fine, but then I restarted or logged out and back in, and now they are not working any more, what’s wrong?

The actions are all enabled by the Keyboard Maestro Engine. You can start it by launching the Keyboard Maestro application, or have the engine start automatically by enabling the “Launch Engine at Login” preference.

My Macros are not working, what’s wrong?

In order for macros that use Select Menu Item or Manipulate Window to work you must enable access for assistive devices in the Universal Access system preference.

Also, check that the macro group that contains the macros is enabled for the

application you are testing with.

The Window Switcher shows an empty list, what’s wrong?

In order for the Window Switcher to work you must enable access for assistive devices in the Universal Access system preference.

The Program, Window and Clipboard Switcher does not work at all, what’s wrong?

The Hot Keys for the Program, Window, and Clipboard Switcher are all effectively Macros in the Global Macro  roup, so if you have disabled this group (or restricted it to certain applications), that will affect the Switcher Hot Keys as well.

I want to use command-tab for the Program Switcher, but the system overrides it, what’s wrong?

Apple have claimed the command-tab keystroke and refuse to allow third parties to override this. While we disagree with this behaviour by Apple, we are not willing to implement a hack solution that may cause compatibility problems, especially in light of this being a deliberate action. We write software that is as robust as we can make it and are not likely to add solutions that attempt to specifically do things Apple does not want us to do.

You can use PullTab together with Unsanity APE to disable the command-tab facility in the Dock and then you will be able to use Keyboard Maestro with command-tab.

How do I get more help?

For more information about a specific Keyboard Maestro feature consult the Keyboard Maestro Documentation, post a question to the Keyboard Maestro User Group, visit the Keyboard Maestro web site or contact us.

We always respond to email, however email is no longer a guaranteed medium and spam filters can delete your message to us or our message to you. Messages sent using the feedback form will always get to us, emails sent to us will pretty much always get to us, but if you do not receive a response within one business day check your spam filters to see if they have trapped our reply. If you use the feedback form and want a reply, make sure you enter your email address!

Glossary

Classic Mac OS
Apple’s operating system version 8.0 through 9.x. Keyboard Maestro requires Mac OS X and will not run on Classic Mac OS.
Clipboard
The clipboard is where you store items when you Copy and Paste. When you Copy an item, it is temporarily stored in the Clipboard and when you Paste, the item is copied from the Clipboard into your currently location.
Clipboard Switcher
is a feature of Keyboard Maestro that allows you to switch between a set of named clipboards.
Excluded Applications
is the set of applications that should not appear in the Program Switcher list, allowing you to hide programs you rarely want to switch to.
Fast Launch Applications
is the set of applications that always appear in the Program Switcher list, allowing you to quickly launch them.
Global Macro Group
a predefined Macro Group that always exists and is the default location for new Macros.
Help Viewer
Apple’s Help Viewer application is the standard Mac OS X help system, used for display application and system documentation.
Hot Key
A key press that acts as a Macro Trigger to start the execution of a Macro.
Keyboard Maestro Engine
The process that enables your Macros, Program Switcher, and Clipboard Switcher to work even after you quit Keyboard Maestro.
Mac OS X
Apple's new operating system versions 10.0 and up. Keyboard Maestro only supports version 10.2 and up, and 10.2.6 and up is recommended.
Mac OS
Apple’s operating system we've all come to know and mostly love.
Macro
a set of Macro Triggers together with a sequence of Macro Actions. Any one of the triggers will begin the execution of the sequence of actions.
Macro Action
an action you wish to perform, such as opening a file, typing some text, controlling iTunes, and so on.
Macro Group
a set of Macros which can be restricted to only a defined set of applications.
Macro Palette
a floating palette containing any active Macros that have a Macro Palette trigger. The palette only appears in applications with at least once active Macro Palette triggered Macro.
Macro Trigger
an event, such as a Hot Key, application launch, time of day, that starts the execution of a Macro.
Michael Kamprath
the developer of Program Switcher for Classic Mac OS and the original developer of Keyboard Maestro.
PowerMate
Griffin Technology’s PowerMate is an input device which can be used to trigger macros.
Program Switcher
the premier application management utility for Classic Mac OS, written by Michael Kamprath it was in part the inspiration for Keyboard Maestro and forms one of the three components of Keyboard Maestro.
Shortcut
a Shortcut is another name for a Macro (it is also another name for an Alias but that is a different context to the normal Keyboard Maestro Macro context).
URL
an acronym for Uniform Resource Locator, this is the standard way of specifying a location on the Internet. It starts with a protocol, followed by a colon and then the location. For example, “http://www.stairways.com/”.

Administrative Details

Requirements

Keyboard Maestro 2 requires Mac OS X 10.2 or later.

Distribution

You may distribute this program in any way you wish as long as you only distribute the unmodified Keyboard Maestro package, as downloaded from www.stairways.com. You may not break Keyboard Maestro up into its component files and distribute parts of it separately.

History

Following on the success of Program Switcher for Classic Mac OS, Michael Kamprath wrote Keyboard Maestro for Mac OS X and released it in early 2002. Incorporating an impressively powerful hot key macro facility, as well as Program and Clipboard Switching facilities, it rapidly became an indispensable tool for many Mac OS X users, including us here at Stairways Software.

Development continued on version 1 through the end of 2002, and then work began on version 2. The first beta of 2.0 was released in early 2003 and development continued until the 2.0b6 beta released in May 2003. After that, life and work got in the way. Keyboard Maestro languished for over a year as Michael found that he did not have the time or energy to continue development.

Around May 2004, we contacted Michael as a concerned user to query the long delay in the eagerly awaited 2.0 release. When we learned that Michael was considering abandoning the program we offered to purchase it from him to ensure that we would not lose this valuable tool, as well as to continue the fine tradition that he had started.

On June 30, 2004 the deal was struck and Stairways Software acquired all the rights to Keyboard Maestro. Our aim was to resolve the outstanding issues with Keyboard Maestro and release 2.0 as soon as possible, which we have now done.

Keyboard Maestro 2.0 introduces many new Macro Triggers (such as Application, Time of Day, PowerMate, and so on), macro sets to allow easy control over when macros are active, many new actions, key repeat

Going forward, we plan to aggressively develop Keyboard Maestro, bringing it to new levels of both power and ease of use in the long tradition of both Mac OS and Stairways Software.

Credits

Thanks to Michael Kamprath for all his work producing Keyboard Maestro.

Thanks to Alan Gentle for many example Macro ideas.

Thanks also to the many others who have provided input and support over the past decade.

Warranty

This program should do what we have described in this document. If it does not, you can simply stop using it. If you purchase it, and within 30 days find that it does not do what we have described here, then you can request a refund and your money will be refunded and we will cancel your license.

Licenses

Keyboard Maestro is copyright 2004 Stairways Software Pty Ltd. All Rights Reserved. You may use this program for a short trial period and then you must purchase the program or stop using it.

Trademarks owned by Third Parties such as Mac, PowerMate, BBEdit, are owned by their respective owners and no license is granted for their use.

Fine Print

Keyboard Maestro, keyboardmaestro.com and stairways.com are the property of Stairways Software Pty Ltd. Stairways Software Pty Ltd hereby disclaims all warranties relating to this software, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Stairways Software Pty Ltd will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if Stairways Software Pty Ltd or an agent of theirs has been advised of the possibility of such damages. In no event shall Stairways Software Pty Ltd be liable for any damages, regardless of the form of the claim. The person using the software bears all risk as to the quality and performance of the software.

Close

Feedback Form

Please provide any feedback you may have


Email Address:
Subject:
Feedback:


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.

Logo

Conduct your Mac Like a Pro!

About Download Purchase Table of Contents

Documentation

Keyboard Maestro

Old Documentation

Powered By Interarchy