Mac Shortcuts Automation: The Practitioner's Reference

TL;DR: Shortcuts has shipped on every Mac since macOS Monterey (2021), and macOS Tahoe (26) finally gave it the piece Mac automators waited four years for: personal automations with triggers like folder changes, external drives, Wi-Fi, displays, and app launches.³⁴ The app runs shortcuts from the menu bar, Spotlight, Finder Quick Actions, keyboard shortcuts, and a real command-line tool (shortcuts run, list, view, sign).¹² Every app can add actions through the App Intents framework, which is the same surface Siri, Spotlight, and Apple Intelligence call.¹³ Scripts and AI agents drive shortcuts three ways: the CLI, the shortcuts:// URL scheme, and the scriptable Shortcuts Events background process.¹⁹¹¹ The permission model is the part to learn first: consent prompts that are invisible in the app will silently stall an unattended run.

Apple told developers “Shortcuts is the future of Mac automation” at WWDC 2021.⁵ The future arrived in two halves. The first half shipped immediately: a native SwiftUI app on macOS Monterey with iCloud sync, an Automator migration tool, and full support for shell scripts and AppleScript inside the editor.⁵ The second half took four more macOS releases. Until macOS Tahoe, a Mac shortcut only ran when something asked for it; there were no triggers, so “automation” meant remembering to click. Tahoe closed that gap with personal automations built for the Mac (folder and external drive triggers) alongside the familiar iOS set (Time of Day, Bluetooth), and added a Use Model action that puts Apple Intelligence in the middle of a shortcut’s data flow.³⁴

The result is a system worth learning properly. Shortcuts on the Mac in 2026 is four things at once:

1. A no-code editor with hundreds of built-in actions, from file operations to window management to on-device AI
2. An automation engine with system-event triggers, new in macOS Tahoe
3. A command-line citizen: shortcuts run behaves like any other Unix tool, with stdin, stdout, exit codes, and pipes¹
4. An action registry for every app: anything an app exposes through App Intents appears in Shortcuts automatically, on the Mac as everywhere else¹³⁴

The gap between casual and expert use comes down to five systems: the actions catalog (what exists), automation triggers (when things run), the CLI and scripting bridges (how code calls in), signing and sharing (how shortcuts travel), and the permission model (why unattended runs stall). Each gets its own part below.

Every claim in this guide is grounded in Apple’s documentation, WWDC sessions, or direct inspection of macOS 26.5 (Shortcuts 7.0) on the machine it was written on. Where a fact came from the operating system itself (the shortcuts(1) man page, the Shortcuts Events scripting dictionary, the actions in the WorkflowKit framework), the citation says so.

Key Takeaways

• Automations are the headline. macOS Tahoe brought personal automations to the Mac: folder changes, external drives, displays, Wi-Fi, Bluetooth, Stage Manager, app launch/quit, Time of Day, and more, each runnable immediately or after confirmation.³⁴
• The CLI is real, not a toy. shortcuts run "Name" -i input -o output supports stdin (-i -), stdout (-o -), typed output via Uniform Type Identifiers, and exits 0 on success, 1 on error. Pipe it like any Unix tool.¹²
• Three script entry points, one rule. Use the CLI from shells and CI, the shortcuts:// URL scheme only from other apps, and Shortcuts Events (AppleScript/ScriptingBridge) when you need results back in a scripting context without opening the app.¹⁹¹¹
• Signing gates distribution. A .shortcut file must be signed to travel: shortcuts sign -m anyone notarizes through iCloud so anyone can import; the default people-who-know-me mode signs locally and limits import to people who have you in Contacts.²⁷
• App Intents is the developer surface. An app that ships App Intents gets Shortcuts actions on the Mac for free, and those same intents power Spotlight and automations, including iOS apps installed on Apple silicon Macs.⁴¹³
• Consent is the failure mode. Shortcuts asks Allow Once / Always Allow / Don’t Allow per shortcut, per data type. Script-running actions sit behind a global “Allow Running Scripts” switch. A headless run that hits an unanswered prompt just waits.¹⁶⁸

How to Use This Guide

Table of Contents

Part 1: Foundations

1. What Is Shortcuts on Mac
2. Ways to Run a Shortcut
3. Shortcuts vs Automator vs AppleScript

Part 2: Actions

1. How Actions Compose
2. The Actions Catalog
3. Scripting Actions
4. Window Management Actions
5. The Use Model Action

Part 3: Automations

1. Automation Triggers on macOS
2. Automation Patterns That Work

Part 4: The Command Line and URL Schemes

1. The shortcuts CLI
2. Scripting the App with Shortcuts Events
3. URL Schemes

Part 5: Sharing and Distribution

1. Sharing Formats and Signing

Part 6: The Developer Surface

1. App Intents: How Apps Add Actions
2. Spotlight and Automations Run Your Intents
3. Driving Shortcuts from Scripts and Agents

Part 7: Operations and Reference

1. Permissions and Consent (TCC)
2. Troubleshooting
3. Quick Reference Card
4. FAQ
5. Changelog
6. References

What Is Shortcuts on Mac

Shortcuts is Apple’s automation app: you chain actions (single-purpose steps) into a shortcut (a saved workflow), then run it by click, voice, keystroke, trigger, or command line. Apple’s own definition is worth keeping in mind because it explains the entire design: “An action is the building block of a shortcut. Each shortcut comprises a series of actions, and each action is a single step that performs a particular function.”¹²

The app arrived on the Mac with macOS Monterey in 2021, ported from iOS but written almost entirely in SwiftUI so the same codebase serves both platforms.⁵ Three design decisions from that first release still define the Mac experience in 2026:

• iCloud sync is the default. Open Shortcuts on a new Mac and your existing library appears, synced from iPhone and iPad. A shortcut built on one device runs on the others, minus platform-specific actions.⁵¹²
• Apps supply actions. “Like on iOS, any app on the Mac can provide actions to Shortcuts.”⁵ In 2026 that pipeline is the App Intents framework, covered in Part 6.
• Scripts are first-class. Monterey shipped “full support for AppleScripts and Shell Scripting” with “new actions, built right into Shortcuts, that let you write and run scripts directly inside the Shortcuts editor,” so Shortcuts wraps the older automation stack instead of replacing it.⁵

What Monterey did not ship was triggers. From 2021 through 2024, a Mac shortcut ran only when something invoked it. macOS Tahoe (26) changed that in 2025 by bringing personal automations to the Mac, with trigger types built specifically for desktop workflows (folder contents changed, external drive connected) plus the established iOS set.³⁴ Tahoe also added the Use Model action, which sends data through Apple Intelligence models mid-shortcut.³⁴

Version landmarks:

Throughout the guide, “verified on macOS 26.5” means checked directly against Shortcuts 7.0 on the Mac used to write it.

Ways to Run a Shortcut

Shortcuts on the Mac is unusually generous with entry points. All of the following invoke the same shortcut; they differ in where the input comes from and where the output lands.¹²¹⁰

Two details save time later. First, Quick Action and Services entries receive the current selection as shortcut input, which is why file-processing shortcuts should declare their accepted input types (the editor’s “Receive” configuration) rather than assume text. Second, the last three rows are the programmable surface; they get their own sections because their input/output contracts differ.

Shortcuts vs Automator vs AppleScript

All three Apple automation systems still ship with macOS in 2026 (Automator remains in /System/Applications, verified on macOS 26.5), and each still has a job. The framing that holds up: Shortcuts is the integration layer, AppleScript is the app-control language, and shell scripts are the computation layer. Automator is in maintenance: functional, unchanged, and explicitly succeeded by Shortcuts.⁵¹⁴

The migration path is real but lossy at the edges. Apple built a converter into Shortcuts: drag a .workflow file into the app (or Control-click → Open With → Shortcuts) and “Shortcuts can convert most Automator workflows into shortcuts that carry out the same functions, events, and automations.”¹⁴¹⁵ “Most” is Apple’s word, and the practical reading is: standard file, image, and text actions convert cleanly; obscure third-party Automator actions and Watch Me Do recordings are where conversion degrades. Shortcuts even retains a Watch Me Do action name in its internals as part of that compatibility story (visible in the framework’s action table, verified on macOS 26.5).¹⁶

When to reach past Shortcuts. Deep per-app control (iterating Mail messages, manipulating Finder windows programmatically, driving apps with rich scripting dictionaries) is still AppleScript’s home turf. Complex text processing, API orchestration, and anything you would write in Python or zsh anyway belongs in a script. The practitioner’s move is composition, not allegiance: a shortcut that gathers input from a trigger, hands it to a shell script for the heavy lifting, and uses native actions for notifications and file placement gets the best of each system. The Scripting Actions section covers the mechanics.

How Actions Compose

Every shortcut is a pipeline. Each action takes input (often the previous action’s output), does one thing, and produces output. Three mechanics make the pipeline expressive:

• Magic variables. Every action’s output is automatically available to later actions as a variable, without declaring anything. Click a parameter field, choose Select Magic Variable, and pick any earlier action’s output. Set Variable and Get Variable exist for explicit naming, and Add to Variable accumulates lists (all three are built-in actions, verified on macOS 26.5).¹⁶
• Content types, converted on demand. Actions declare what they accept (files, images, text, URLs, dates). When output and input types differ, Shortcuts coerces where it can: pass a web page to a text action and you get the page text. The editor’s “Receive” configuration at the top of a shortcut declares what the whole shortcut accepts from Quick Actions, Services, or the CLI’s --input-path.
• Flow control as actions. If, Repeat, Repeat with Each, Choose from Menu, Wait to Return, Stop This Shortcut, and Stop and Output are ordinary actions.¹⁶ Stop and Output matters more on the Mac than anywhere else: it defines what a shortcut returns to the command line, a pipe, or a calling script.¹

The composition primitive is Run Shortcut: one shortcut invoking another by name, with input.¹⁶ Apple’s guidance is explicit that nesting should use the action, not URL schemes: “If you’d like to run one shortcut from another shortcut, use the Run Shortcut action instead of a URL scheme.”⁹ Treat shortcuts like functions: small single-purpose shortcuts (normalize a filename, post to a webhook, resize to thumbnail) composed by a coordinator shortcut scale far better than one 60-action monolith, and each piece stays independently testable from the CLI.

The Actions Catalog

The built-in library is large: the English strings table inside macOS 26.5’s WorkflowKit framework (the private framework behind Shortcuts) lists 361 distinct action names.¹⁶ The number overstates what you’ll see in the editor: the table includes iOS-only actions and legacy integrations from the app’s Workflow-era ancestry. What follows is the Mac-relevant catalog, organized by what automators actually reach for. Every action name below appears verbatim in that table, verified on macOS 26.5.¹⁶

Files and Finder

System and Apps

Web and Data

Get Contents of URL plus the Dictionary actions form a workable REST client: request, parse JSON, extract values, no code. When payloads get complex, hand off to a shell script with curl and jq instead of fighting nested dictionaries in the editor.

Text, Images, and Media

Calendar, Reminders, Contacts, Notes

Find Calendar Events, Add New Calendar, Edit Calendar Event, Find Reminders, New Reminder, Edit Reminder, Find Contacts, Edit Contact, Create New Note, Get Notes, Delete Notes, and their Get Details of… counterparts cover the productivity apps.¹⁶ The Find/Filter + Get Details pairing is the pattern: query a collection, then extract fields from the matches.

Shortcuts, Meta, and Flow

A meta-automation note for Part 6: Get My Shortcuts and Get Details of Shortcut let a shortcut enumerate the library, which pairs with shortcuts list on the CLI side for building tooling around your collection.¹⁶²

Scripting Actions

Five actions bridge Shortcuts to the traditional automation stack, and all five sit behind one global switch. In Shortcuts → Settings → Advanced, “Allow Running Scripts” must be on before any of them will run; the app’s own description of the setting names exactly which actions it gates: “When enabled, the actions ‘Run AppleScript’, ‘Run Shell Script’, ‘Run JavaScript for Mac Automation’, ‘Run JavaScript on Web Page’ and ‘Run Script Over SSH’ can be run” (verified on macOS 26.5).⁸¹⁷ Apple’s documentation adds the warning that running shortcuts with scripts could cause data loss — the setting exists because these five actions run with your full user privileges, outside the guardrails that contain ordinary actions.⁸

Run Shell Script

The workhorse. You pick the shell, paste the script, and choose how input arrives. The two input modes come straight from the action’s own documentation: “to stdin: The input will be converted to a file and directed to the stdin pipe of the script. as arguments: The input will be converted to a list of strings and passed as arguments to the script.”¹⁷

Practical implications of those two modes:

• stdin mode suits text and single files: pbpaste-style processing, JSON through jq, anything that reads a stream.
• arguments mode suits multiple files: each input item lands in "$@", so for f in "$@"; do ... done handles a Finder selection correctly, spaces and all.
• Output is whatever the script writes to stdout, and it flows to the next action like any other output.

Run AppleScript and Run JavaScript for Mac Automation

Both embed Open Scripting Architecture scripts with an on run {input, parameters} entry point (AppleScript) or a run(input, parameters) function (JXA). Reach for them when the job is controlling another app: Finder window arrangement, Mail rules, anything with a scripting dictionary. The return value becomes the action’s output.

Run Script Over SSH

Runs a shell script on a remote host with host, port, user, and authentication configured in the action. The killer use is symmetric with the CLI: a Mac in your office can expose repeatable operations to any machine that can reach it over SSH, and a shortcut can push work out to Linux boxes without leaving the Shortcuts editor.

Run JavaScript on Web Page

Runs JavaScript against the current Safari page and returns the result. Apple gates it behind both the scripts switch and a per-run permission prompt because arbitrary page-context JavaScript is a data-exfiltration surface.⁸

Window Management Actions

Shortcuts ships native window control on the Mac: Find Windows, Move Window, and Resize Window.¹⁶ They read as minor catalog entries and turn out to be the building blocks for keyboard-driven window layouts without third-party tools.

• Find Windows queries open windows (sortable and filterable in the editor) and outputs window objects.
• Move Window takes a window and a position. Its parameter summary reads “Move ⟨Window⟩ to ⟨Position⟩,” with an optional custom variant “Move ⟨Window⟩ to ⟨Position⟩ ⟨X Coordinate⟩, ⟨Y Coordinate⟩” (verified on macOS 26.5).¹⁶
• Resize Window takes a window and a target: “Resize ⟨Window⟩ to ⟨Configuration⟩,” with a custom variant accepting explicit ⟨Width⟩ × ⟨Height⟩.¹⁶

The built-in windowing positions in the framework’s strings table: Full Screen, Left, Right, Top, Bottom, thirds (Left Third, Middle Third, Right Third), corner variants (Top/Bottom Leading and Trailing), and a custom Window Location and Size format (verified on macOS 26.5).¹⁶ Combine Find Windows (frontmost window) → Resize Window (Left) with a keyboard shortcut and you have a one-key window command. Split Screen Apps handles the two-app case in one action.¹⁶

The Use Model Action

New in macOS Tahoe and the most consequential single action Apple has added since the Mac port: Use Model sends data to an Apple Intelligence model mid-shortcut and hands the response to the next action.³⁴

Three model choices, per Apple’s WWDC session on the feature: a large server-based model on Private Cloud Compute, the on-device model “for simple requests without network connection,” and ChatGPT “for broad world knowledge.”⁴

Three output shapes, and choosing deliberately is the skill:⁴

1. Text (including rich text) for summaries and rewrites.
2. Dictionary for structured extraction; Apple’s example is pulling vendor, amount, and date out of invoices. Dictionary output is what makes Use Model composable: downstream actions read fields instead of parsing prose.
3. App entities: content objects from apps that expose them through App Intents. Apple frames the relationship as “If App Intents are the actions or verbs from your app, App Entities are the nouns,”⁴ and Use Model can reason over those nouns directly (filter these notes, pick the relevant calendar event).

A Follow Up toggle allows iterating on the model’s response inside the same run.⁴

One engineering caution: model output is nondeterministic, so the same input can produce different results run to run. For automations, that argues for the dictionary output shape (schema-constrained), small focused prompts, and a validation step (an If action checking required fields) before the result touches files or messages. Treat Use Model like a flaky network call: useful, wrapped in checks.

For the developer view of the same feature (what your app should expose so Use Model can reason over it), see Part 6 and the App Intents cluster on this site, starting with App Intents Are Apple’s New API to Your App.

Automation Triggers on macOS

Automations are shortcuts with a trigger attached: “run this when that happens,” no click required. They arrived on the Mac in macOS Tahoe, and Apple built Mac-specific triggers rather than porting the iOS list wholesale: “we’re bringing personal automations to the Mac, with new automation types like folder and external drive automations built specifically for Mac, along with automation types you might already be familiar with from iOS, like Time of Day and Bluetooth.”⁴

Create them from the Automation area of the Shortcuts app. Each automation pairs one trigger with a set of actions and one policy decision: Run Immediately (no interaction, the point of automation) or Run After Confirmation (a notification asks first).³¹⁸ Start new automations with confirmation until you trust them, then flip to immediate.

The trigger catalog on macOS Tahoe:³⁴¹⁸

Two shifts follow from the design. First, the Mac finally has an Apple-native answer to “watch this folder and process what lands in it” that syncs and edits like any other shortcut (Automator’s Folder Actions did the watching but not the rest). Second, because automations run shortcuts, everything in this guide compounds: a Folder trigger can feed Run Shell Script; an App trigger can call Use Model; an External Drive trigger can kick off an SSH job.

Automation Patterns That Work

Patterns that hold up in daily use, assembled entirely from documented pieces:

The hot folder. Folder trigger on ~/Inbox → Filter Files (extension is pdf) → Extract Text from Image or Get Text from PDF → Use Model with dictionary output (vendor, date, total) → Rename File and Move File into an archive hierarchy. The classic Automator use case, upgraded with on-device extraction and model-shaped naming.³⁴¹⁶

The desk dock. Display trigger (external display connects) → Open App for your work set → Move Window and Resize Window into your layout → Set Focus to Work. Reverse it on disconnect. One trigger rebuilds the whole desk layout with no manual dragging.³¹⁶

The ingest drive. External Drive trigger → Get Contents of Folder on the card’s DCIM → Filter Files by date → Save File into a dated folder → Show Notification with the count. Confirmation mode is wise here: drives you didn’t expect shouldn’t trigger bulk copies.³¹⁸

The escape hatch to real code. Any trigger → Run Shell Script with input as arguments → your existing script. The trigger system is the valuable part; nothing requires the logic to live in Shortcuts actions. A two-action automation (trigger + script) gives launchd-style event handling with a UI, sync, and consent management for free.⁸¹⁷

Meeting-adjacent contexts. Focus trigger (Work Focus on)¹⁸ → Set Volume, Quit App for distractions, Open App for notes. With Focus sharing across devices enabled in System Settings, the Mac reacts to a Focus turned on from the iPhone.

Constraints to design around: an automation lives on the Mac where you create it, so a Folder automation built on the MacBook won’t fire on the Mac mini even though the shortcut library itself syncs (set up the trigger on each machine that needs it), and the trigger list has no “web request received” entry (bridge that with Run Script Over SSH from the sender’s side, or a folder watched by a cloud-sync client).³¹⁸

The shortcuts CLI

macOS has shipped a real command-line interface for Shortcuts since Monterey: /usr/bin/shortcuts, documented in shortcuts(1) and in Apple’s user guide.¹² It has four subcommands. I verified everything below against macOS 26.5.

shortcuts run <shortcut-name-or-identifier> [-i <input-path> ...] [-o <output-path>] [--output-type <UTI>]
shortcuts list [-f <folder-name>] [--folders] [--show-identifiers]
shortcuts view <shortcut-name>
shortcuts sign [-m <mode>] -i <input> -o <output>

shortcuts run

Runs a shortcut by name or by identifier. “Running shortcuts from the command line is no different from running shortcuts in the Shortcuts app,”¹ which cuts both ways: full action access, and full permission prompts (see Permissions).

Apple’s canonical example runs an image-combining shortcut over a folder of JPEGs:¹

shortcuts run "Combine Images" -i ~/Desktop/*.jpg -o ~/Desktop/combined.png

The CLI honors the Unix contract on both ends. Exit status: “The shortcuts command will exit 0 on a successful run or 1 on error.”¹ Output piping works when the shortcut ends with output or contains Stop and Output:¹

# Pipe shortcut output onward, typed as RTFD
shortcuts run "Make Meeting Notes" --output-type com.apple.rtfd | ...

# Feed stdin in, capture stdout out
echo "quarterly report" | shortcuts run "Slugify" -i - -o -

One documented trap: piping text into shortcuts run delivers it as text. “When you pass a file path using a pipe, the path is treated as text. Use the -i flag to ensure your input is treated as file paths.”¹

And one design rule from Apple worth engraving: “the most efficient shortcuts are ones that don’t show alerts or ask for input. When a shortcut asks for input, the command line process pauses, awaiting user input.”¹ For anything headless, that pause is a hang. Build CLI-facing shortcuts to take all parameters from input.

shortcuts list

Lists shortcut names, one per line. --folders lists folders instead; -f <folder> scopes to a folder (“none” for shortcuts outside any folder); --show-identifiers appends each shortcut’s UUID.² Identifiers matter for automation: names collide and get renamed, UUIDs don’t. shortcuts run accepts either.²

shortcuts list --show-identifiers | grep "Deploy"

shortcuts view

Opens the named shortcut in the Shortcuts editor.² Useful at the end of tooling: a script that detects a failing shortcut can drop you into its editor.

shortcuts sign

Signs a .shortcut file for distribution; covered with the sharing formats in Part 5.²

Scripting the App with Shortcuts Events

The third programmatic surface is the scripting interface. Shortcuts on the Mac registers two scriptable targets: the Shortcuts app itself, and a faceless background helper, Shortcuts Events (bundle identifier com.apple.shortcuts.events, verified on macOS 26.5).¹¹ The scripting dictionary embeds the reason for the split: “To run a shortcut in the background, without opening the Shortcuts app, tell ‘Shortcuts Events’ instead of ‘Shortcuts’.”¹¹

The dictionary is small and stable. Shortcuts have readable properties name, subtitle, id, folder, color, icon, accepts input, and action count; folders have name and id; and the one verb is run, with an optional with input parameter and a result.¹¹

AppleScript:

tell application "Shortcuts Events"
    run shortcut "Slugify" with input "Quarterly Report Draft"
end tell

JXA:

const se = Application("Shortcuts Events");
const result = se.shortcuts.byName("Slugify").run({withInput: "Quarterly Report Draft"});

Python via ScriptingBridge or py-applescript targets the same interface; with PyObjC’s ScriptingBridge, SBApplication.applicationWithBundleIdentifier_("com.apple.shortcuts.events") returns the app object whose shortcuts() collection mirrors the dictionary above.¹¹

When to prefer it over the CLI: you’re already inside an AppleScript/JXA context, you want the shortcut’s result as a native object rather than serialized stdout, or you’re driving runs from an app that can send Apple Events but shouldn’t shell out. The first Apple Event a host process sends to Shortcuts Events raises macOS’s standard Automation consent prompt (System Settings → Privacy & Security → Automation), one more prompt to clear before unattended operation.⁶

The dictionary also exposes organize-level access (folders and shortcut metadata are readable, folder assignment writable), so library housekeeping (inventory reports, folder audits) can be scripted without touching the UI.¹¹

URL Schemes

Shortcuts registers the shortcuts:// URL scheme (plus legacy workflow:// from the app’s pre-acquisition ancestry, verified on macOS 26.5).¹⁹ URLs are the integration path for other apps: launchers, note apps with link fields, anything that can open a URL. Apple’s guidance is direct: “You should only run shortcuts with a URL if you’re integrating from another app outside of Shortcuts.”⁹

Run a shortcut:⁹

shortcuts://run-shortcut?name=[name]&input=[input]&text=[text]

• name (required): percent-encoded shortcut name.
• input: either text or clipboard. With text, the text parameter’s value becomes the shortcut input; with clipboard, “the contents of the Clipboard are used” and text is ignored.⁹

shortcuts://run-shortcut?name=Lookup%20Goetta&input=text&text=goetta%20is%20great
shortcuts://run-shortcut?name=Add%20to%20Notes&input=clipboard

x-callback-url adds response handling for round-trips:²⁰

shortcuts://x-callback-url/run-shortcut?name=Calculate%20Tip&input=text&text=24.99&x-success=...&x-error=...&x-cancel=...

• x-success opens on success, with the shortcut’s text output appended as a result parameter.
• x-error opens on failure, with an errorMessage parameter.
• x-cancel opens if the user cancels, and provides no output.²⁰

From the shell, open "shortcuts://run-shortcut?..." works, but prefer shortcuts run there: the CLI returns exit codes and output directly instead of bouncing through URL callbacks. The scheme’s remaining niche on the Mac is app-to-app integration and links inside documents.

Sharing Formats and Signing

Shortcuts travel two ways, and both end in a trust decision.⁷

iCloud links. In the app: share → Copy iCloud Link. Anyone with the link adds the shortcut to their library, which makes links the low-friction path for publishing to the world. Treat a link as public once sent.⁷

Shortcut files. File → Export produces a .shortcut file (UTI com.apple.shortcut, verified on macOS 26.5).¹⁹⁷ Export forces the trust choice:

• Anyone: “Anyone can run your shortcut.” Apple receives a copy of the shortcut for validation.⁷
• People Who Know Me: “Only people who have you in their contacts will be able to run your shortcut.” Your contact info is embedded in the file for that check.⁷

The CLI mirrors the same two modes and names the mechanism, per shortcuts(1) on macOS 26.5: people-who-know-me “will sign locally, but only your devices, or people who have your contact info in their contacts, will be able to import the shortcut,” while anyone “will notarize via iCloud, and allow anyone to import the shortcut.”²

shortcuts sign -m anyone -i "Deploy Notes.shortcut" -o "Deploy Notes-signed.shortcut"

That command is the distribution answer for teams and CI: exported shortcuts signed with -m anyone import cleanly for recipients who have never met you. Because the anyone mode notarizes through iCloud, plan on an iCloud-signed-in session and network access before wiring it into a build pipeline.²

Importing is drag-and-drop: double-click a .shortcut file, drag it into the app, or drop it on the Dock icon; .workflow files convert from Automator on the way in.¹⁵ Shortcuts shared outside the Gallery carry a caveat Apple states plainly: “Apple cannot verify the authenticity or behavior of shortcuts shared privately.”⁶ Corporate fleets have a separate path: Apple Configurator supports Shortcuts automations for managed workflows.²¹

Settings → Advanced also holds Private Sharing, the switch governing import of privately shared (contact-gated) shortcuts, alongside Allow Running Scripts and Allow Sharing Large Amounts of Data.⁶⁸ A received shortcut that won’t import usually traces to one of: unsigned file, contact-gated file from someone not in your contacts, or Private Sharing disabled.

App Intents: How Apps Add Actions

Everything in the catalog so far is Apple’s. The other half of the library comes from installed apps, and since 2022 the pipeline for that is one framework: App Intents (iOS 16, macOS 13).¹³ An app defines types conforming to AppIntent (a verb: parameters plus a perform() method), optionally AppEntity (a noun: a typed piece of the app’s content with an identifier and display representation), and the system takes it from there. The same definitions surface in Shortcuts, Siri, Spotlight, widgets, and Apple Intelligence; Shortcuts is one projection of the app’s intent schema, not a separate integration.¹³⁴

Two adoption levels matter to how an app shows up on the Mac:

• Actions: every non-hidden intent appears as an action in the Shortcuts editor under the app’s name, composable with everything in this guide.
• App Shortcuts: intents wrapped in an AppShortcutsProvider ship as ready-to-run shortcuts the moment the app is installed, no user assembly required, with Siri trigger phrases attached.¹³

The framework’s reach keeps widening at the yearly cadence. The WWDC25 session on Shortcuts and Spotlight states the current contract for the Mac directly: “As long as your intent is available on macOS, they will also be available to use in Shortcuts to run as a part of Automations on Mac. This includes iOS apps that are installable on macOS.”⁴ An iPhone app running on an Apple silicon Mac contributes actions to Mac automations without a single line of Mac-specific code.

Apple’s adoption guidance from the same session, condensed: expose your content as entities with “key properties that you would want a model to be able to reason over” (the Use Model action consumes them), ship find actions so queries work, use attributed strings where rich text makes sense, and keep parameter summaries readable.⁴

Design guidance for intent authors, distilled from shipping App Intents in production apps:

• Intents are API. Treat names, parameters, and entity identifiers as a contract; renaming breaks users’ shortcuts the way renaming an endpoint breaks clients.
• Background beats foreground. An intent that can run without opening the app composes into automations; one that requires foregrounding interrupts whatever the user was doing. Separate them deliberately.⁴
• Return values feed pipelines. An intent that returns an entity or value gives Shortcuts users something to chain; one that returns nothing is a dead end in the graph.

This site covers the developer side in depth in the App Intents cluster: App Intents Are Apple’s New API to Your App (the adoption argument and a production walkthrough), App Intents 2.0 in iOS 26 (Visual Intelligence, snippets, deferred properties), App Intents in iOS 27 (long-running background intents, syncable entities, Spotlight reindexing), and App Intents vs MCP (when the same capability should also be an agent tool).

Spotlight and Automations Run Your Intents

macOS Tahoe extended where intents execute, and the two additions change what “adopting App Intents” buys on the Mac.⁴

Spotlight runs intents inline. “This year, you can now run actions from your app directly from Spotlight on Mac. Your apps can show actions in Spotlight by adopting App Intents, just like what you do for Shortcuts.”⁴ The requirements are specific enough to audit against:

1. The parameter summary (“a short, natural language representation of what the app intent does”) “must contain all required parameters that don’t have a default value.”⁴
2. The intent must not opt out of discovery: isDiscoverable false or assistantOnly true removes it from Spotlight.⁴
3. Suggestions and search come from the entity layer: implement suggested entities or an enumerable entity query for the picker, and an entity string query or indexed entities for search-as-you-type.⁴

Automations run intents unattended. Because Tahoe automations execute shortcuts and shortcuts execute intents, a folder change or drive mount can now invoke an app’s intent with no user present.⁴ For intent authors, that raises the bar set in the previous section: an intent that assumes a foreground user (presents UI, requires confirmation) breaks silently inside a Run Immediately automation. Audit each intent for unattended execution: what happens when nobody is watching the screen?

Together the two form Apple’s quiet architectural statement: the intent, not the app window, is the unit of functionality on the Mac. Spotlight is the interactive caller, automations the unattended one, Shortcuts the composition layer between them.

Driving Shortcuts from Scripts and Agents

Shortcuts occupies a specific niche in agent and script architectures: it is the least-privileged, most user-auditable way for outside code to invoke Mac capabilities. An AI agent with shell access can do most things directly, but routing an operation through a shortcut has properties raw shell doesn’t: the operation is user-defined and user-editable, its permissions are granted per shortcut and revocable in one click, and its blast radius is visible in the editor.⁶ Think of the shortcut layer as a capability catalog the human curates and the agent calls.

One hard requirement before any of this works: the CLI needs a logged-in GUI session. Every shortcuts subcommand — including list — talks to a helper application in the user’s Aqua session and fails with “Couldn’t communicate with a helper application” when none exists (verified on macOS 26.5). SSH-only sessions, headless CI runners, and launch daemons hit this wall; run agent and scheduled invocations inside a logged-in user session — a launchd agent, not a daemon.

The invocation contract, in agent terms:¹²

Structured data crosses the boundary as text. The workable pattern is JSON over stdin/stdout: the caller pipes a JSON document in (-i -), the shortcut parses it with Get Dictionary from Input, does its work, and ends with Stop and Output feeding a dictionary back as text.¹¹⁶ The shortcut becomes a typed function with a documented schema; keep a README of each shortcut’s expected input and output shape next to whatever agent configuration invokes it.

Timeouts are the caller’s job. Because a shortcut that shows an alert pauses the CLI process indefinitely,¹ every unattended caller should wrap invocation with a timeout and treat expiry as failure:

# macOS ships no timeout(1); gtimeout comes from `brew install coreutils`
if ! output=$(gtimeout 120 shortcuts run "$UUID" -i - -o - <<<"$payload"); then
  echo "shortcut failed or timed out" >&2
fi
# no-Homebrew alternative using the system perl:
#   perl -e 'alarm shift; exec @ARGV' 120 shortcuts run "$UUID" -i - -o - <<<"$payload"

Warm the permissions before going unattended. Run each shortcut interactively once and answer Always Allow to its prompts; confirm the run is prompt-free from a terminal before an agent or launchd job calls it.⁶¹ The permissions section explains what you’re pre-clearing.

Choose the entry point by caller type. Shell-capable callers (agents, CI, launchd agents, Makefiles — all inside a logged-in session) use the CLI. Apple Event contexts (AppleScript apps, PyObjC daemons) use Shortcuts Events and get native return values.¹¹ Sandboxed or URL-only contexts use shortcuts://run-shortcut with x-callback for results.⁹²⁰ All three run the same shortcut; only the transport differs.

The symmetric direction also works: shortcuts as agent frontends. A shortcut with a keyboard shortcut or menu bar slot that gathers context (selection, clipboard, frontmost app), passes it to Run Shell Script invoking your agent CLI, and displays the result — the operating system’s input surfaces become UI for whatever tooling lives underneath.¹⁰¹⁷

Permissions and Consent (TCC)

Shortcuts inherits macOS’s consent-first security model, and every automation failure that isn’t a logic bug eventually traces here. The model has four layers; know which one is prompting and the fixes become mechanical.

1. Per-shortcut data consent. The first time a shortcut touches a protected resource, Shortcuts asks: “If a Privacy dialog appears requesting access to data, choose Allow Once, Always Allow, or Don’t Allow.” Always Allow means “the Shortcuts app won’t ask you for access the next time you run the shortcut.”⁶ Grants are per shortcut, per resource, and inspectable: each shortcut’s details pane has a Privacy tab where individual grants can be revoked, and “To remove access to all data for this shortcut, click Reset Privacy.”⁶

2. The scripts gate. The five script actions run only with Settings → Advanced → Allow Running Scripts enabled (exact list above).⁸ The setting is global, not per shortcut; enabling it for one hot-folder script enables it for every imported shortcut, which is a reason to read imported shortcuts before running them.⁶

3. System TCC prompts. Actions that reach protected OS territory (Files and Folders, Automation/Apple Events for scripting other apps, Accessibility for input control) trigger the system-level dialogs governed by System Settings → Privacy & Security. These attach to the responsible process, which is why a shortcut can behave differently in the app, from the CLI, and under an automation: different launch contexts, separately granted.⁶

4. Automation run policy. Each automation’s Run Immediately vs Run After Confirmation setting decides whether the trigger itself requires a human.¹⁸

Operational rules that follow:

• Prompts don’t render where nobody’s looking. Headless contexts (SSH sessions, CI runners, agents) inherit rule one of the CLI section: an unanswered consent dialog is an indefinite pause.¹ Pre-clear interactively.
• Reset Privacy is the clean-slate debugger. When a shortcut misbehaves after edits, resetting its grants and re-running interactively re-surfaces every prompt in order.⁶
• Imported shortcuts deserve reading. Apple validates “Anyone”-signed shortcuts but “cannot verify the authenticity or behavior of shortcuts shared privately.”⁶⁷ The Privacy tab shows what a shortcut has been granted; the editor shows what it does. Both take one minute.

Troubleshooting

Quick Reference Card

# Run
shortcuts run "Name"                          # by name
shortcuts run 8F3A...-UUID                    # by identifier (stable)
shortcuts run "Name" -i file.jpg -o out.png   # file in, file out
echo data | shortcuts run "Name" -i - -o -    # stdin → stdout
shortcuts run "Name" --output-type public.plain-text | pbcopy

# Inspect
shortcuts list                                # names
shortcuts list --show-identifiers             # names + UUIDs
shortcuts list --folders                      # folders
shortcuts list -f "Folder"                    # scoped
shortcuts view "Name"                         # open in editor

# Distribute
shortcuts sign -m anyone -i in.shortcut -o out.shortcut
shortcuts sign -m people-who-know-me -i in.shortcut -o out.shortcut

# Exit codes: 0 success, 1 error

-- Background run with result (no app window)
tell application "Shortcuts Events" to run shortcut "Name" with input "payload"

shortcuts://run-shortcut?name=Name&input=text&text=payload
shortcuts://run-shortcut?name=Name&input=clipboard
shortcuts://x-callback-url/run-shortcut?name=Name&x-success=app://ok&x-error=app://fail

Checklists. Unattended-ready shortcut: no alerts or Ask Each Time parameters; consent pre-cleared with Always Allow; invoked by UUID; caller enforces a timeout; ends with Stop and Output.¹⁶ Distribution-ready file: exported, signed -m anyone, input contract documented.²⁷

FAQ

How do I run a Mac shortcut from Terminal? shortcuts run "Shortcut Name", optionally with -i for input files (or - for stdin), -o for output (or - for stdout), and --output-type with a Uniform Type Identifier. The command exits 0 on success and 1 on error, so it composes with &&, if, and make like any Unix tool.¹²

Does macOS finally have Shortcuts automations like iOS? Yes, since macOS Tahoe (26). Triggers include Time of Day, Alarm, Email, Message, Folder changes, External Drive, Display, Wi-Fi, Bluetooth, Battery Level, Charger, App open/quit, Focus, and Stage Manager, each configurable to run immediately or after confirmation.³⁴¹⁸

What does shortcuts sign -m anyone actually do? It notarizes the shortcut file through iCloud so that anyone can import it. The default mode, people-who-know-me, signs locally and restricts import to your own devices and people who have your contact info in Contacts.²

How do apps add their own actions to Shortcuts on Mac? By adopting the App Intents framework. Intents appear as Shortcuts actions automatically, and an AppShortcutsProvider ships zero-setup App Shortcuts with the app. Intents available on macOS also run from Spotlight and inside Tahoe automations, including intents from iOS apps installed on Apple silicon Macs.¹³⁴

How should a script or AI agent invoke shortcuts? Use the CLI: discover with shortcuts list --show-identifiers, invoke by UUID, pass JSON over stdin, read results from stdout, and wrap every call in a timeout because a shortcut that prompts will pause forever (macOS ships no timeout(1) — use gtimeout from coreutils or your language’s process timeout). Pre-authorize each shortcut’s permission prompts interactively before unattended use. From AppleScript contexts, target Shortcuts Events to run without opening the app.¹²¹¹

Can Shortcuts replace Automator? For most workflows, yes; Apple calls Shortcuts the future of Mac automation and built a converter that imports most .workflow files directly. Automator still ships and still runs existing workflows, so migration is a choice, not a deadline.⁵¹⁴¹⁵

Changelog

References