Run macro
Runs another macro, waits for it to finish and hands back what it returned.
Run macro
Keyboard Maestro: ExecuteMacro, ExecuteSubroutine
Details #
Starts the macro named in id and, by default, waits until it ends. The called macro gets its own run, its own variables and its own row in the Trace, linked to yours.
Pass values with inputs, an object whose keys are the called macro's declared inputs. In the editor, choose the macro from the list and fill one field per input. Inputs are checked against the declared type, and a missing input with no default makes the called run fail. A macro that declares its result (see Functions) fails the call when it returns the wrong type. The called macro sees only its inputs and shared. variables. Your local variables do not follow it.
Set on to run the macro on another of your Macs instead: the Run macro form gets a Run on menu once a second Mac signs in to your iCloud account. See Several Macs for how that works, how it travels, and what happens while that Mac sleeps.
A Return a value inside the called macro sets its result. Name a variable in into to receive it. The step's output also carries runId, status and returned.
You can give the macro's id or its name. A name that matches more than one macro runs the first match, so prefer the id.
With wait set to false the step starts the macro the normal way (queue and concurrency rules included) and moves on. The output holds the new runId. No result comes back, so into stays unset.
- Run another macro with n = 21 → answer
- Show “Got {{ answer }}”
Parameters #
| Parameter | Type | Required | Values | What it does |
|---|---|---|---|---|
id | text | Yes | The macro's id or name. | |
inputs | record | Object of input values. Values may contain {{ }}. | ||
into | text | Variable that receives the returned value, or null when the macro returned nothing. | ||
macroName | text | |||
on | text | Run the macro on another of your Macs: its host id (the editor writes this) or its name. Left out, the macro runs on this Mac. The macro must be exposed on that Mac (its Agent settings), and id is that Mac's macro. Settings > Macs lists your Macs. | ||
onName | text | , macroName: The Mac's name and the macro's name as the editor last saw them, so the sentence reads "Run Start recording on Mac Studio" while that Mac is offline. The run ignores both. | ||
sample | any value | Used only in a dry run. The step is not executed there; sample becomes the value of into. | ||
wait | yes / no | Default true. Set false to start the macro and carry on without its result. While it waits, the step's time limit is what is left of your macro's own (not the 10 s a step gets by default), and the called macro still stops at its own timeout. |
Every step also accepts label, onFailure, timeout and dryRunSafe.
Examples #
- Run another macro
- Show “Cleanup started”
Gotchas #
On another Mac, wait (default
true) waits for that Mac's answer for this step's timeout (a minute by default). A Mac that is asleep or off doesn't answer: the step fails with "Mac Studio hasn't answered; the request is queued" and the request runs when the Mac wakes. With waitfalsethe step succeeds at once with statusqueued.On another Mac, a dry run of your macro dry-runs the macro there. Stopping your run stops the run there.
Calls nest at most 16 deep. A macro that calls itself runs into that limit and fails.
A called macro shares its caller's time budget: it cannot outlive the caller's timeout.
The called macro's Only if is skipped. You asked for it by name, so it runs.
A dry run does not run the called macro. It sets into to
sample, or to an empty text.