Keyboard Maestro IconKeyboard Maestro

Conduct your Mac Like a Pro!

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. 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.

Macros Window

Now click the + button below the Macro Groups list.

Macro Group Editor

Enter the name of your new Macro Group.

You can choose to target the macros in your Macro Group at specific applications.

By default, Macro Groups and their Macros are available in all applications, that is they are always ready to be triggered. These are especially useful for Macros that give you instant access to applications or documents, or type in globally applicable text. For example you might have a Macro to launch your email client or word processor, a Macro to open your financial accounts, and a macro to type your name or email address.

To have macros only active in specific applications, set the Macro Group to be “Available in the following applications” and add the desired applications to the list.

For example, you could have macros targeted at:

To have macros active everywhere except specific applications, set the Macro Group to be active in “Available except in the following applications” and add the desired applications to the list. For example, you could exclude macros from triggering in games. Also, if you have an application that uses lots of function keys for crucial tasks, you could exclude that application to allow you to use the functions keys for macros elsewhere without conflicting with that application.

You can also choose to activate the macros manually (either for a single macro, or toggled on and off) or display the macros is a floating macro palette. The options are:

To have the macros in a Macro Group always ready to be triggered, set the Macro Group to be “Always activated”.

To have macros that are active only immediately after you trigger the Macro Group, set the Macro Group to be activated “Activated for one action when”. The macros in the Macro Group will be enabled when you trigger the Macro Group and will remain enabled until either any macro is triggered or you press any other key. You could use this to create a set of related actions with easily remembered hot keys that will not conflict with normal use because they are not activated until you trigger the group. For example, you could have a group of macros to launch various applications so that command-control-L activated the group, and then a single letter press launched the application (eg M for Mail, S for Safari, F for Finder).

As with each of the following options, you can trigger the macro group by pressing a Hot Key, by selecting from the Status Menu, or by clicking on the global floating palette.

To have Macros that are active after you trigger the Macro Group, set the Macro Group to be “Activated/deactivated when”. The Macros in the Macro Group will be enabled when you trigger the Macro Group and will remain enabled until you trigger the Macro Group again. You could use this to create a set of related actions with easily remembered hot keys that will not conflict with normal use because they are not activated until you press the group Hot Key. For example, you could have a group of macros to move and resize windows and have command-control-W activate the group. Then a single arrow key press moves the front window. When the window is positioned, press command-control-W a second time to disable the macros.

To have Macros that are active and displayed only immediately after you trigger the Macro Group, set the Macro Group to “Shows a palette for one action when”. The Macros in the Macro Group will be displayed in a floating Macro Palette and enabled when you trigger the Macro Group and will remain displayed until either any macro is triggered or you press any other key. You could use this to create a set of related actions that do not even need a Hot Key. For example, you could have a group of macros to launch various applications like Mail, Safari and the Finder so when you press command-control-L, a palette of these macros is displayed and a single click will launch the application.

To have Macros that are active and displayed after you trigger the Macro Group, set the Macro Group to “Shows/hides a palette when”. The Macros in the Macro Group will be displayed in a floating Macro Palette and enabled when you trigger the Macro Group and will remain displayed until you trigger the Macro Group again. You could use this to create a set of related actions that do not even need a Hot Key. For example, you could have a group of macros to align objects in a CAD program, so when you press command-control-A, a palette of these macros is displayed and you can click various alignment options (distribute left-right, align top edges) and then close the palette by pressing command-control-A a second time.

To have Macros that are always active and displayed in a palette, set the Macro Group to “Shows a palette until”. The Macros in the Macro Group will be displayed in a floating Macro Palette and enabled. The palette will close when (if) you trigger the Macro Group and will remain closed (and the macros disabled) until you trigger the Macro Group again. You could use this to create a set of related actions that do not even need a Hot Key and that are available in a Macro Palette. You could make the Macro Group available only in a specific application so that it appears only in that application. For example, you could have a group of macros to align objects in a CAD program, and have the Macro Group available (and hence the palette displayed) only in the CAD program.

Even if the macros are displayed in a Palette, the macros can still have Hot Key (or any other kind of) triggers which will be available whenever the macro group is active (ie, whenever the palette is displayed).

You can disable or enable a macro group by selecting it and clicking the button at the bottom of the Groups list. If a Macro Group is disabled, all its contained Macros will be disabled. You can disable or enable a Macro Group from AppleScript with:

tell application "Keyboard Maestro"
  setMacroEnable "Macro Group Name or UID" with/without enable
end tell

You can change the targeting of an existing group by selecting it in the Groups list and clicking the Edit button or by double clicking it.

You can start editing a Macro or Macro Group from AppleScript with:

tell application "Keyboard Maestro"
  editMacro "Macro Group Name or UID"
end tell

To delete a Macro Group, select the macro group and then press the Delete key or click the button at the bottom of the Groups list.

You cannot delete or rename or disable 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, select the desired Macro Group to contain it, and then click the + button below the Macros list. To edit a Macro, select it and click the Edit button (or double click it). The Macro Editor window will be displayed.

Macro Editor Window

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

You can create a new trigger by clicking on the green button. There are several 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. You can delete a trigger by clicking the red button.

You can create a new action by clicking the New Action button or the + button at the bottom of the macro detail view to display the list of actions. 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. You can also drag actions between macros and copy them by option-dragging. You can also Copy and Paste actions You can delete an action by selecting it and pressing the Delete key. You can enable or disable actions by selecting them and clicking the button at the bottom of the macro detail view.

An easy way to generate macro actions is to turn on recording by clicking the Record button at the bottom of the macro detail view 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 need to delete or adjust some of the recorded actions to make a robust macro, but this will be much quicker than creating each macro action manually.

You can display more or less detail about some actions by clicking the disclosure triangle. While disclosed, you can try the action immediately by clicking the Try button at the top right of the action. You can disclose all the actions simultaneously by option clicking on the disclosure triangle.

You can try the actions immediately by selecting some or all of them and clicking the Try button at the bottom of the macro detail view.

Macros are continuously saved, so the macro is live as soon as it is created. It will be available immediately (subject to the restrictions of the Macro Group it is contained in).

You execute a macro’s action sequence by triggering the macro using any of the Macro Triggers you have defined.

If the web server is enabled for remote access, you can trigger a macro remotely after logging in using a web browser or the Keyboard Maestro Control iPhone application.

You can also trigger a macro using AppleScript or another scripting language (select the “Or by script” entry to display script code in various languages such as AppleScript or Perl).

Note that the web server needs to be separately enabled in the Web Server preference pane, and all macros are subject to the restrictions of the Macro Group they are contained in.

You can disable or enable a macro by selecting it and clicking the button at the bottom of the Macros list. You can disable or enable a Macro from AppleScript with:

tell application "Keyboard Maestro"
  setMacroEnable "Macro Name or UID" with/without enable
end tell

You can start editing a Macro or Macro Group from AppleScript with:

tell application "Keyboard Maestro"
  editMacro "Macro Group Name or UID"
end tell

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

Continue on to Macro Actions

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.

Documentation

Old Documentation