Your first macro

You'll build a macro that shows how many characters are on your clipboard whenever you press a hotkey. It has a trigger and three steps, and you'll add a condition afterwards. It never clicks or types anything, so it's safe to run while you learn.

The three rows #

Every macro has the same three rows. If you come from Keyboard Maestro, you know them already: triggers, conditions and actions under other names.

Rows can hold more than one item. A macro with two triggers starts on either. A macro with two conditions needs both to be true. Steps run from top to bottom.

Make the macro #

1. Press ⌘N (File > New Macro). A new macro appears in the selected Group.

2. Rename it. Click the title and type Clipboard length, then press ⏎.

Add the trigger #

Under When, click Add a trigger… (or press ⌥⌘⏎). The chooser opens on a key is pressed with Hotkey first; press ⏎. Then set the key to g and the modifiers to hyper. Hyper is ⌘ ⌃ ⌥ ⇧ together.

Other trigger types are in Triggers.

Add the steps #

Under Do, press ⌘⏎ or click Add a step…. The chooser opens: pick what the step is about on the left and what to do on the right, or type to search. Press ⏎ to add the highlighted step; ⎋ closes it. Adding a trigger, condition or step has the details.

Add these three, in this order:

1. Clipboard: set the operation to get and the variable (into) to text. The step reads the clipboard and stores it in a variable called text.

2. Variable: set the operation to set, the name to n and the value to {{ length(text) }}.

3. Show message (the HUD step): set the text to Clipboard has {{ n }} characters.

Anything inside {{ }} is an expression. Variables and expressions covers them.

Here is the finished macro. Press Try it to dry run it, or Add to Library to keep a copy.

Add a condition #

Say you only want this in Safari. Under Only if, click Add a condition… (or press ⌃⌘⏎) and choose Front app under an app is running. Set the app to Safari's bundle identifier, com.apple.Safari.

If the condition is false when you press the hotkey, the macro doesn't run, and Switchboard records why. See Not fired.

A second condition means both must hold. To flip a condition, turn on Opposite (only if this is not true) in the inspector.

Record or add a step #

There are two ways to get a step into Do.

• Add a step (⌘⏎). You pick a step type and fill in its fields. This works for every step.

• Record (⇧⌘R, or Record in the toolbar). Switchboard steps aside while you click and type in any app, and writes the steps as you go. It names the button, not a screen position. Press ⎋ in the app you are recording, or Stop Recording, to finish. The steps land in Do at your selection as one edit, so ⌘Z takes them all back. Recording needs the Accessibility permission.

To point a step at a different button later, select it and press Re-record in the inspector, then click the element. See Finding things on screen.

Dry run or run #

The Macro menu has three related commands.

In a dry run these steps still run for real:

• Control flow: If, Repeat, Group, Variable, Return, Cancel, Break and Continue.

• Show message and Prompt. A prompt answers with its default.

• Clipboard when it reads.

Every other step is simulated. The trace lists it with the input it would have used, and nothing happens. A step that stores its result with into still sets that variable, to an empty value or to the sample the step declares, so later steps have something to work with.

Dry run anything that types, clicks, sends or deletes before you run it. This macro only shows a message, so press ⌘R on it now. The message appears and the last-run line under the title updates.

Describe it #

Under the name is a line for what this macro does. Type your own, or choose Macro › AI › Describe with AI (or the sparkle button) and Apple Intelligence writes one from the blocks, on your Mac. A line it wrote is the model's until you edit it; then it is yours and Switchboard never changes it. If you change the blocks later, the model's line turns grey with Update beside it. The line shows in the sidebar tooltip, the palette, your iPhone, share pages and to agents. After an import, Describe all after import fills in every macro; Macro › AI › Describe All Undescribed Macros does it later.

Read the trace #

Every run leaves a trace: one row per step with its result and time.

1. Press ⌘2 to open Activity.

2. Select the run. Its steps are listed in order, each with a status such as ok, failed or simulated, and how long it took.

3. Click Show in and out on a step to see exactly what went in and what came out.

4. Open in Editor jumps to the macro. Run Again (⌘R in Activity) repeats the run, as a dry run if the original was one.

If a step fails, the run stops there by default. The trace names the step, what it was looking for and a suggestion. Each step can change this with If it fails in the inspector: Stop the macro, Carry on, or Take the failure branch, which runs steps of your own.

When it does not start #

If you press the hotkey and nothing happens, open Activity and choose Not Fired in the Show menu. It lists every event that matched a trigger but started nothing, with the reason: the Group is off, the front app is out of scope, two macros share the hotkey, secure input is on, the macro is off, Switchboard is paused, or an Only if was false (with the values it saw). See Triggers.

Next steps #

• Choose a trigger

• Use variables and expressions

• Debug a macro

• Make a macro with AI