Mac Shortcuts 자동화: 실무자 참고서 (2026)

요약: Shortcuts는 macOS Monterey(2021)부터 모든 Mac에 기본으로 제공되었고, macOS Tahoe(26)에서는 Mac 자동화 사용자들이 4년 동안 기다려 온 기능이 마침내 추가됐어요. 폴더 변경, 외장 드라이브, Wi-Fi, 디스플레이, 앱 실행 같은 조건을 트리거로 사용하는 개인용 자동화 기능이에요.³⁴ 메뉴 막대, Spotlight, Finder Quick Actions, 키보드 단축키뿐 아니라 실제 명령줄 도구(shortcuts run, list, view, sign)에서도 단축어를 실행할 수 있어요.¹² 모든 앱은 App Intents 프레임워크를 통해 actions를 추가할 수 있으며, Siri, Spotlight, Apple Intelligence도 같은 인터페이스를 사용해요.¹³ 스크립트와 AI 에이전트는 CLI, shortcuts:// URL scheme, 스크립트로 제어할 수 있는 Shortcuts Events 백그라운드 프로세스라는 3가지 방법으로 단축어를 실행해요.¹⁹¹¹ 가장 먼저 익혀야 할 부분은 권한 모델이에요. 앱에서는 눈에 보이는 동의 요청도 무인 실행 중에는 표시되지 않아 작업이 아무런 안내 없이 멈출 수 있어요.

Apple은 WWDC 2021에서 개발자들에게 “Shortcuts가 Mac 자동화의 미래”라고 밝혔어요.⁵ 그 미래는 두 단계로 나뉘어 찾아왔어요. 첫 번째 단계는 곧바로 제공됐어요. macOS Monterey에 네이티브 SwiftUI 앱이 추가됐고, iCloud 동기화와 Automator 마이그레이션 도구를 지원했으며, 편집기 안에서 셸 스크립트와 AppleScript를 완전히 사용할 수 있게 됐어요.⁵ 두 번째 단계는 macOS가 4번 더 출시된 뒤에야 완성됐어요. macOS Tahoe 이전에는 무언가가 요청해야만 Mac 단축어가 실행됐어요. 트리거가 없었기 때문에 “자동화”라고 해도 결국 사용자가 직접 클릭해야 했어요. Tahoe는 Mac에 맞게 설계된 개인용 자동화 기능을 추가해 이 공백을 해소했어요. 폴더와 외장 드라이브 트리거뿐 아니라 iOS에서 익숙한 Time of Day, Bluetooth 트리거도 사용할 수 있어요. 또한 단축어의 데이터 흐름 중간에서 Apple Intelligence를 활용하는 Use Model action도 추가됐어요.³⁴

그 결과, 이제 이 시스템은 제대로 익힐 만한 가치가 있어요. 2026년 Mac의 Shortcuts는 다음 4가지 역할을 동시에 수행해요.

1. 코드 없는 편집기로, 파일 작업과 창 관리부터 기기 내 AI까지 수백 가지 기본 actions를 제공해요
2. 자동화 엔진으로, macOS Tahoe에서 새롭게 추가된 시스템 이벤트 트리거를 사용해요
3. 명령줄 도구로, shortcuts run은 stdin, stdout, 종료 코드, 파이프를 지원하며 다른 Unix 도구처럼 작동해요¹
4. 모든 앱을 위한 action 레지스트리로, 앱이 App Intents를 통해 공개한 모든 기능은 다른 플랫폼과 마찬가지로 Mac의 Shortcuts에도 자동으로 나타나요¹³⁴

일반적인 활용과 전문가 수준의 활용을 가르는 요소는 5가지 시스템이에요. actions 카탈로그(무엇을 사용할 수 있는지), 자동화 트리거(언제 실행되는지), CLI와 스크립팅 연결 기능(코드에서 어떻게 호출하는지), 서명과 공유(단축어를 어떻게 전달하는지), 권한 모델(무인 실행이 왜 멈추는지)이에요. 아래에서 각 항목을 별도의 부분으로 살펴봐요.

이 가이드의 모든 설명은 Apple 문서, WWDC 세션 또는 작성에 사용한 기기에서 macOS 26.5(Shortcuts 7.0)를 직접 확인한 결과를 근거로 해요. 운영체제 자체에서 확인한 사실이라면 출처에 이를 명시했어요. 예를 들어 shortcuts(1) man page, Shortcuts Events 스크립팅 사전, WorkflowKit 프레임워크의 actions가 여기에 해당해요.

핵심 요점

• 자동화가 핵심입니다. macOS Tahoe는 폴더 변경, 외장 드라이브, 디스플레이, Wi-Fi, Bluetooth, Stage Manager, 앱 실행/종료, 시간대 등 Mac용 개인 자동화를 도입했습니다. 각각 즉시 실행하거나 확인 후 실행할 수 있습니다.³⁴
• CLI는 실제 도구이지 장난감이 아닙니다. shortcuts run "Name" -i input -o output는 stdin(-i -), stdout(-o -), Uniform Type Identifiers를 통한 형식 지정 출력, 성공 시 종료 코드 0과 오류 시 1을 지원합니다. 다른 Unix 도구처럼 파이프로 연결할 수 있습니다.¹²
• 스크립트 진입점은 3개이며, 원칙은 하나입니다. 셸과 CI에서는 CLI를 사용하고, 다른 앱에서만 shortcuts:// URL scheme을 사용하세요. 앱을 열지 않고 스크립팅 컨텍스트에서 결과를 받아야 한다면 Shortcuts Events(AppleScript/ScriptingBridge)를 사용하세요.¹⁹¹¹
• 서명이 배포를 좌우합니다. .shortcut 파일은 공유하려면 서명해야 합니다. shortcuts sign -m anyone은 iCloud를 통해 공증하므로 누구나 가져올 수 있습니다. 기본 people-who-know-me 모드는 로컬에서 서명하며 Contacts에 사용자를 등록한 사람으로 가져오기를 제한합니다.²⁷
• App Intents가 개발자용 표면입니다. App Intents를 제공하는 앱은 Mac에서 Shortcuts actions를 자동으로 얻습니다. 동일한 intents는 Apple silicon Mac에 설치된 iOS 앱을 포함해 Spotlight와 자동화도 구동합니다.⁴¹³
• 동의가 실패 지점입니다. Shortcuts는 shortcut과 데이터 유형별로 Allow Once / Always Allow / Don’t Allow을 묻습니다. 스크립트를 실행하는 actions는 전역 “Allow Running Scripts” 스위치 뒤에 있습니다. 응답하지 않은 프롬프트를 만나는 headless 실행은 그대로 대기합니다.¹⁶⁸

이 가이드 사용 방법

목차

Part 1: 기초

1. Mac의 Shortcuts란 무엇인가
2. shortcut 실행 방법
3. Shortcuts vs Automator vs AppleScript

Part 2: Actions

1. Actions를 조합하는 방법
2. Actions Catalog
3. Scripting Actions
4. 창 관리 actions
5. Use Model action

Part 3: 자동화

1. macOS의 자동화 트리거
2. 효과적인 자동화 패턴

Part 4: 명령줄과 URL Schemes

1. shortcuts CLI
2. Shortcuts Events로 앱 스크립팅하기
3. URL Schemes

Part 5: 공유 및 배포

1. 공유 형식 및 서명

Part 6: 개발자용 표면

1. App Intents: 앱이 actions를 추가하는 방법
2. Spotlight와 자동화가 intents를 실행하는 방법
3. 스크립트와 agents에서 Shortcuts 구동하기

Part 7: 운영 및 참고 자료

1. 권한 및 동의(TCC)
2. 문제 해결
3. 빠른 참조 카드
4. FAQ
5. 변경 이력
6. 참고 자료

Mac의 Shortcuts란 무엇인가

Shortcuts는 Apple의 자동화 앱입니다. actions(단일 목적 단계)를 연결해 shortcut(저장된 workflow)을 만들고, 클릭, 음성, 키 입력, 트리거 또는 명령줄로 실행합니다. Apple의 정의는 전체 설계를 설명하므로 기억해 둘 만합니다. “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.”¹²

이 앱은 2021년 macOS Monterey와 함께 iOS에서 Mac으로 옮겨왔으며, 동일한 코드베이스가 두 플랫폼을 지원하도록 거의 전부 SwiftUI로 작성되었습니다.⁵ 첫 출시 당시의 3가지 설계 결정은 2026년에도 Mac 경험을 규정합니다.

• iCloud 동기화가 기본입니다. 새 Mac에서 Shortcuts를 열면 iPhone과 iPad에서 동기화된 기존 라이브러리가 표시됩니다. 한 기기에서 만든 shortcut은 플랫폼 전용 actions를 제외하고 다른 기기에서도 실행됩니다.⁵¹²
• 앱이 actions를 제공합니다. “Like on iOS, any app on the Mac can provide actions to Shortcuts.”⁵ 2026년에는 이 파이프라인이 Part 6에서 다루는 App Intents framework입니다.
• 스크립트는 기본 기능입니다. Monterey는 “full support for AppleScripts and Shell Scripting”과 함께 “new actions, built right into Shortcuts, that let you write and run scripts directly inside the Shortcuts editor”를 제공했습니다. 따라서 Shortcuts는 이전 자동화 스택을 대체하는 대신 감싸는 역할을 합니다.⁵

Monterey에 없었던 것은 트리거였습니다. 2021년부터 2024년까지 Mac shortcut은 어떤 것이든 호출할 때만 실행되었습니다. macOS Tahoe(26)는 2025년에 데스크톱 workflow에 맞춘 트리거 유형(폴더 내용 변경, 외장 드라이브 연결)과 기존 iOS 트리거 세트를 통해 Mac에 개인 자동화를 도입하며 이를 바꿨습니다.³⁴ Tahoe는 shortcut 중간에 데이터를 Apple Intelligence models로 전송하는 Use Model action도 추가했습니다.³⁴

버전별 주요 변화:

이 가이드에서 “macOS 26.5에서 확인됨”은 작성에 사용한 Mac의 Shortcuts 7.0에서 직접 확인했다는 뜻입니다.

shortcut 실행 방법

Mac의 Shortcuts는 진입점을 매우 폭넓게 제공합니다. 아래의 모든 방법은 동일한 shortcut을 호출하며, 입력의 출처와 출력이 도착하는 위치만 다릅니다.¹²¹⁰

이후 시간을 절약해 주는 세부 사항이 2가지 있습니다. 먼저 Quick Action과 Services 항목은 현재 선택 항목을 shortcut 입력으로 받습니다. 따라서 파일 처리 shortcuts는 텍스트를 가정하기보다 허용하는 입력 유형(편집기의 “Receive” 설정)을 선언해야 합니다. 둘째, 마지막 3개 행은 프로그래밍 가능한 표면입니다. 입력 및 출력 계약이 서로 다르므로 각각 별도 섹션에서 다룹니다.

Shortcuts와 Automator, AppleScript 비교

Apple의 자동화 시스템 3가지는 2026년에도 모두 macOS에 포함되어 있으며(Automator는 여전히 /System/Applications에 있고 macOS 26.5에서 확인했어요), 각각 맡은 역할이 있어요. 가장 적절한 구분은 다음과 같아요. Shortcuts는 통합 계층이고, AppleScript는 앱 제어 언어이며, 셸 스크립트는 연산 계층이에요. Automator는 유지 관리 단계에 있어요. 정상적으로 작동하고 달라진 점은 없지만, Apple은 Shortcuts가 그 역할을 이어받는다고 명확히 밝혔어요.⁵¹⁴

실제로 마이그레이션할 수 있지만 일부 세부 기능은 손실될 수 있어요. Apple은 Shortcuts에 변환기를 내장했어요. .workflow 파일을 앱으로 드래그하거나 Control-클릭 → Open With → Shortcuts를 선택하면 “Shortcuts는 대부분의 Automator 워크플로를 동일한 기능, 이벤트, 자동화를 수행하는 단축어로 변환할 수 있어요.”¹⁴¹⁵ 여기서 “대부분”은 Apple이 직접 사용한 표현이에요. 실무적으로는 표준 파일, 이미지, 텍스트 동작은 원활하게 변환되지만, 잘 알려지지 않은 서드 파티 Automator 동작과 Watch Me Do 기록은 제대로 변환되지 않을 수 있다는 뜻이에요. Shortcuts는 이러한 호환성을 위해 내부에 Watch Me Do라는 동작 이름까지 유지하고 있어요. 프레임워크의 동작 표에서 확인할 수 있으며 macOS 26.5에서 검증했어요.¹⁶

Shortcuts 이외의 도구를 사용해야 할 때도 있어요. Mail 메시지를 순회하거나, Finder 창을 프로그래밍 방식으로 조작하거나, 풍부한 스크립팅 사전으로 앱을 제어하는 등 앱을 세밀하게 제어하는 작업은 여전히 AppleScript가 가장 잘하는 영역이에요. 복잡한 텍스트 처리, API 조율, 그리고 어차피 Python이나 zsh로 작성할 작업은 스크립트로 처리하는 편이 좋아요. 실무에서는 한 도구만 고집하기보다 조합해서 사용해요. 트리거에서 입력을 수집하고, 무거운 작업은 셸 스크립트에 맡기며, 알림과 파일 배치에는 기본 동작을 사용하는 단축어를 만들면 각 시스템의 장점을 모두 활용할 수 있어요. 구체적인 방법은 스크립팅 동작 섹션에서 설명해요.

동작을 조합하는 방법

모든 단축어는 파이프라인이에요. 각 동작은 입력을 받아(대개 이전 동작의 출력이에요) 한 가지 작업을 수행한 뒤 결과를 출력해요. 다음 3가지 메커니즘을 활용하면 다양한 파이프라인을 만들 수 있어요.

• 매직 변수. 모든 동작의 출력은 따로 선언하지 않아도 이후 동작에서 변수로 자동 사용할 수 있어요. 매개변수 필드를 클릭하고 Select Magic Variable을 선택한 다음, 이전 동작의 출력 중 하나를 고르세요. 명시적으로 이름을 지정할 때는 Set Variable과 Get Variable을 사용하고, 목록을 누적할 때는 Add to Variable을 사용해요. 3가지 모두 내장 동작이며 macOS 26.5에서 확인했어요.¹⁶
• 필요할 때 변환되는 콘텐츠 유형. 동작은 파일, 이미지, 텍스트, URL, 날짜 등 허용하는 입력 유형을 명시해요. 출력과 입력의 유형이 다르면 Shortcuts는 가능한 범위에서 자동으로 변환해요. 예를 들어 웹 페이지를 텍스트 동작에 전달하면 페이지의 텍스트를 얻을 수 있어요. 단축어 편집기 상단의 “Receive” 설정에서는 단축어 전체가 Quick Actions, Services 또는 CLI의 --input-path에서 어떤 입력을 받을지 지정해요.
• 동작으로 구현된 흐름 제어. If, Repeat, Repeat with Each, Choose from Menu, Wait to Return, Stop This Shortcut, Stop and Output은 모두 일반 동작이에요.¹⁶ Stop and Output은 다른 환경보다 Mac에서 특히 중요해요. 단축어가 명령줄, 파이프 또는 호출한 스크립트에 무엇을 반환할지 지정하기 때문이에요.¹

조합의 핵심 요소는 하나의 단축어가 입력과 함께 다른 단축어를 이름으로 호출하는 Run Shortcut이에요.¹⁶ Apple은 중첩 실행에 URL scheme이 아닌 이 동작을 사용하라고 명확히 안내해요. “한 단축어에서 다른 단축어를 실행하려면 URL scheme 대신 Run Shortcut 동작을 사용하세요.”⁹ 단축어를 함수처럼 다루세요. 파일 이름 정규화, 웹훅 전송, 썸네일 크기로 조정처럼 하나의 목적만 수행하는 작은 단축어를 만들고 이를 조정 단축어에서 조합하면, 60개 동작을 담은 하나의 거대한 단축어보다 훨씬 쉽게 확장할 수 있어요. 각 단축어는 CLI에서 독립적으로 테스트할 수도 있어요.

동작 카탈로그

내장 라이브러리는 방대해요. Shortcuts의 기반이 되는 비공개 프레임워크인 macOS 26.5 WorkflowKit 내부의 영어 문자열 표에는 서로 다른 동작 이름이 361개 있어요.¹⁶ 하지만 편집기에서 실제로 표시되는 동작 수는 이보다 적어요. 이 표에는 iOS 전용 동작과 앱이 Workflow였던 시절부터 남아 있는 기존 통합 기능도 포함되어 있기 때문이에요. 아래에서는 자동화 작업에서 실제로 자주 사용하는 Mac 관련 동작을 용도별로 정리해요. 아래의 모든 동작 이름은 macOS 26.5에서 확인한 이 표의 이름을 그대로 사용했어요.¹⁶

파일과 Finder

시스템과 앱

웹과 데이터

Get Contents of URL과 Dictionary 동작을 조합하면 쓸 만한 REST 클라이언트를 만들 수 있어요. 요청을 보내고 JSON을 분석한 다음 값을 추출하는 모든 과정을 코드 없이 처리할 수 있어요. 페이로드가 복잡하다면 편집기에서 중첩된 Dictionary와 씨름하지 말고 curl과 jq를 사용하는 셸 스크립트에 작업을 넘기세요.

텍스트, 이미지, 미디어

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와 각각에 대응하는 Get Details of… 동작으로 생산성 앱을 다룰 수 있어요.¹⁶ 기본 패턴은 Find/Filter와 Get Details의 조합이에요. 컬렉션을 조회한 다음 일치하는 항목에서 필드를 추출해요.

Shortcuts, 메타 기능, 흐름 제어

6부에서 다룰 메타 자동화와 관련해 알아 둘 점이 있어요. Get My Shortcuts와 Get Details of Shortcut을 사용하면 단축어에서 라이브러리의 항목을 열거할 수 있어요. 이를 CLI의 shortcuts list와 조합하면 단축어 모음을 관리하는 도구를 만들 수 있어요.¹⁶²

스크립팅 actions

5개의 action이 Shortcuts를 기존 자동화 도구와 연결하며, 모두 하나의 전역 스위치 뒤에 있습니다. Shortcuts → 설정 → 고급에서 어떤 action이든 실행하려면 “스크립트 실행 허용”을 켜야 합니다. 앱의 설정 설명에는 이 설정이 정확히 어떤 action을 제어하는지도 나와 있습니다. “활성화하면 ‘Run AppleScript’, ‘Run Shell Script’, ‘Run JavaScript for Mac Automation’, ‘Run JavaScript on Web Page’, ‘Run Script Over SSH’ action을 실행할 수 있습니다” (macOS 26.5에서 확인).⁸¹⁷ Apple 문서는 스크립트가 포함된 shortcut을 실행하면 데이터가 손실될 수 있다고 경고합니다. 이 설정이 존재하는 이유는 이 5개의 action이 일반 action을 제한하는 보호 장치 밖에서, 사용자의 전체 권한으로 실행되기 때문입니다.⁸

Run Shell Script

주력 action입니다. shell을 선택하고 스크립트를 붙여 넣은 다음, 입력을 받는 방식을 선택하면 됩니다. 2가지 입력 모드는 action 자체 문서에 그대로 설명되어 있습니다. “to stdin: 입력이 파일로 변환되어 스크립트의 stdin 파이프로 전달됩니다. as arguments: 입력이 문자열 목록으로 변환되어 스크립트에 인수로 전달됩니다.”¹⁷

두 모드의 실질적인 차이는 다음과 같습니다.

• stdin 모드는 텍스트와 단일 파일에 적합합니다. pbpaste 스타일 처리, jq를 통한 JSON, 스트림을 읽는 모든 작업에 사용할 수 있습니다.
• arguments 모드는 여러 파일에 적합합니다. 각 입력 항목이 "$@"에 들어가므로 for f in "$@"; do ... done를 사용하면 공백이 포함된 경우까지 Finder 선택 항목을 올바르게 처리할 수 있습니다.
• 출력은 스크립트가 stdout에 쓰는 내용이며, 다른 출력과 마찬가지로 다음 action으로 전달됩니다.

Run AppleScript 및 Run JavaScript for Mac Automation

두 action 모두 on run {input, parameters} 진입점(AppleScript) 또는 run(input, parameters) 함수(JXA)가 있는 Open Scripting Architecture 스크립트를 포함합니다. 다른 앱을 제어해야 할 때 사용하세요. 예를 들면 Finder 창 배치, Mail 규칙, 스크립팅 사전이 있는 모든 작업입니다. 반환값은 action의 출력이 됩니다.

Run Script Over SSH

action에서 호스트, 포트, 사용자, 인증을 설정한 뒤 원격 호스트에서 shell 스크립트를 실행합니다. 핵심 활용 사례는 CLI와 대칭적입니다. 사무실의 Mac은 SSH로 접근 가능한 모든 머신에 반복 가능한 작업을 제공할 수 있고, shortcut은 Shortcuts 편집기를 벗어나지 않고 Linux 머신으로 작업을 보낼 수 있습니다.

Run JavaScript on Web Page

현재 Safari 페이지에서 JavaScript를 실행하고 결과를 반환합니다. 임의의 페이지 컨텍스트 JavaScript는 데이터 유출 경로가 될 수 있으므로, Apple은 스크립트 스위치와 실행별 권한 확인을 모두 요구합니다.⁸

창 관리 actions

Shortcuts는 Mac에서 Find Windows, Move Window, Resize Window라는 기본 창 제어 기능을 제공합니다.¹⁶ 카탈로그의 작은 항목처럼 보이지만, 타사 도구 없이 키보드로 창 레이아웃을 제어하는 구성 요소가 됩니다.

• Find Windows는 열려 있는 창을 조회하며(편집기에서 정렬 및 필터링 가능), 창 객체를 출력합니다.
• Move Window는 창과 위치를 받습니다. 매개변수 요약은 “Move ⟨Window⟩ to ⟨Position⟩”이며, 선택적 사용자 지정 형태로 “Move ⟨Window⟩ to ⟨Position⟩ ⟨X Coordinate⟩, ⟨Y Coordinate⟩”를 제공합니다(macOS 26.5에서 확인).¹⁶
• Resize Window는 창과 대상 값을 받습니다. “Resize ⟨Window⟩ to ⟨Configuration⟩”이며, 사용자 지정 형태에서는 명시적인 ⟨Width⟩ × ⟨Height⟩를 받을 수 있습니다.¹⁶

프레임워크의 문자열 테이블에 있는 기본 창 위치는 Full Screen, Left, Right, Top, Bottom, 3분할(Left Third, Middle Third, Right Third), 모서리 형태(Top/Bottom Leading 및 Trailing), 사용자 지정 Window Location and Size 형식입니다(macOS 26.5에서 확인).¹⁶ Find Windows(가장 앞 창) → Resize Window(Left)를 키보드 shortcut과 결합하면 키 하나로 창을 제어할 수 있습니다. Split Screen Apps는 2개 앱의 경우를 하나의 action으로 처리합니다.¹⁶

Use Model action

macOS Tahoe에 새로 추가된 Use Model은 Mac 포팅 이후 Apple이 추가한 가장 중요한 단일 action입니다. shortcut 실행 중간에 데이터를 Apple Intelligence 모델로 보내고, 응답을 다음 action에 전달합니다.³⁴

Apple의 이 기능 WWDC 세션에 따르면 모델은 3가지 중에서 선택할 수 있습니다. Private Cloud Compute의 대규모 서버 기반 모델, “네트워크 연결 없이 간단한 요청을 처리하는” 온디바이스 모델, 그리고 “폭넓은 세계 지식”을 위한 ChatGPT입니다.⁴

출력 형태도 3가지이며, 의도적으로 선택하는 것이 중요합니다.⁴

1. 요약과 재작성에는 Text(서식 있는 텍스트 포함)를 사용합니다.
2. 구조화된 추출에는 Dictionary를 사용합니다. Apple의 예시는 청구서에서 공급업체, 금액, 날짜를 추출하는 것입니다. Dictionary 출력은 Use Model을 조합 가능하게 만듭니다. 후속 action이 산문을 파싱하는 대신 필드를 읽을 수 있기 때문입니다.
3. App entities: App Intents를 통해 이를 노출하는 앱의 콘텐츠 객체입니다. Apple은 이 관계를 “App Intents가 앱의 action 또는 동사라면, App Entities는 명사입니다”라고 설명하며,⁴ Use Model은 이 명사를 직접 추론할 수 있습니다(이 노트 필터링, 관련 캘린더 이벤트 선택).

Follow Up 토글을 사용하면 같은 실행 안에서 모델의 응답을 반복해 다룰 수 있습니다.⁴

엔지니어링 측면에서 한 가지 주의할 점이 있습니다. 모델 출력은 비결정적이므로 같은 입력도 실행마다 다른 결과를 낼 수 있습니다. 자동화에서는 Dictionary 출력 형태(스키마 제약), 작고 집중된 프롬프트, 결과가 파일이나 메시지에 닿기 전 검증 단계(필수 필드를 확인하는 If action)를 사용하는 편이 좋습니다. Use Model은 불안정한 네트워크 호출처럼 다루세요. 유용하지만 검사를 감싸야 합니다.

같은 기능을 개발자 관점에서 살펴보려면(앱이 Use Model이 추론할 수 있도록 무엇을 노출해야 하는지) Part 6와 이 사이트의 App Intents 묶음을 확인하세요. App Intents Are Apple’s New API to Your App에서 시작할 수 있습니다.

macOS의 자동화 트리거

자동화는 트리거가 연결된 shortcut입니다. 클릭할 필요 없이 “이 일이 발생하면 저 작업을 실행”합니다. macOS Tahoe에서 Mac에 도입됐으며, Apple은 iOS 목록을 그대로 옮기는 대신 Mac에 특화된 트리거를 만들었습니다. “Mac을 위해 특별히 설계된 폴더 및 외장 드라이브 자동화 같은 새로운 자동화 유형과, Time of Day 및 Bluetooth처럼 iOS에서 이미 익숙할 수 있는 자동화 유형을 함께 Mac에 개인 자동화를 도입합니다.”⁴

Shortcuts 앱의 Automation 영역에서 생성하세요. 각 자동화는 하나의 트리거와 action 집합, 그리고 하나의 정책 선택을 결합합니다. Run Immediately(상호작용 없음, 자동화의 목적) 또는 Run After Confirmation(알림으로 먼저 확인)입니다.³¹⁸ 새 자동화는 신뢰할 수 있을 때까지 확인 모드로 시작한 다음 즉시 실행으로 전환하세요.

macOS Tahoe의 트리거 카탈로그:³⁴¹⁸

이 설계에서 2가지 변화가 따라옵니다. 첫째, Mac에는 마침내 “이 폴더를 감시하고 여기에 들어오는 항목을 처리”하는 Apple 기본 방식이 생겼습니다. 다른 shortcut처럼 동기화하고 편집할 수 있습니다(Automator의 Folder Actions는 감시는 했지만 나머지는 처리하지 못했습니다). 둘째, 자동화는 shortcut을 실행하므로 이 가이드의 모든 기능이 결합됩니다. Folder 트리거는 Run Shell Script로 전달할 수 있고, App 트리거는 Use Model을 호출할 수 있으며, External Drive 트리거는 SSH 작업을 시작할 수 있습니다.

실제로 유용한 자동화 패턴

문서에 설명된 요소만으로 구성해 일상적으로 안정적으로 사용할 수 있는 패턴입니다.

핫 폴더. ~/Inbox의 폴더 트리거 → 파일 필터링(확장자가 pdf) → 이미지에서 텍스트 추출 또는 PDF에서 텍스트 가져오기 → 사전 형식의 출력(업체, 날짜, 총액)으로 Use Model 사용 → 파일 이름을 변경하고 보관 계층 구조로 파일 이동. Automator의 전형적인 사용 사례를 온디바이스 추출과 모델이 구성한 파일 이름으로 개선한 방식이에요.³⁴¹⁶

데스크 도크. 디스플레이 트리거(외부 디스플레이 연결) → 업무용 앱 모음 열기 → 원하는 레이아웃에 맞게 윈도우 이동 및 크기 조절 → 집중 모드를 업무로 설정. 연결이 해제되면 반대로 실행하세요. 하나의 트리거만으로 직접 드래그하지 않고 전체 데스크 레이아웃을 다시 구성할 수 있어요.³¹⁶

가져오기 드라이브. 외장 드라이브 트리거 → 카드의 DCIM 폴더 내용 가져오기 → 날짜별로 파일 필터링 → 날짜별 폴더에 파일 저장 → 파일 개수가 포함된 알림 표시. 여기서는 확인 모드를 사용하는 편이 현명해요. 예상하지 못한 드라이브가 대량 복사를 실행해서는 안 되기 때문이에요.³¹⁸

실제 코드로 빠져나가는 비상구. 임의의 트리거 → 입력을 인수로 전달해 Run Shell Script 실행 → 기존 스크립트 실행. 중요한 부분은 트리거 시스템이며, 로직을 반드시 Shortcuts actions로 작성할 필요는 없어요. 트리거와 스크립트로 구성된 2개 actions 자동화만으로 UI, 동기화, 동의 관리 기능이 포함된 launchd 방식의 이벤트 처리를 별도 비용 없이 구현할 수 있어요.⁸¹⁷

회의 전후의 컨텍스트. 집중 모드 트리거(업무 집중 모드 켜짐)¹⁸ → 음량 설정, 방해되는 앱 종료, 메모 앱 열기. System Settings에서 기기 간 집중 모드 공유를 활성화하면 iPhone에서 집중 모드를 켰을 때 Mac도 반응해요.

설계할 때 고려할 제약도 있어요. 자동화는 생성한 Mac에만 존재하므로 Shortcuts 라이브러리 자체가 동기화되더라도 MacBook에서 만든 폴더 자동화는 Mac mini에서 실행되지 않아요. 필요한 각 기기에서 트리거를 설정하세요. 또한 트리거 목록에는 “웹 요청 수신” 항목이 없어요. 발신 측에서 Run Script Over SSH를 사용하거나 클라우드 동기화 클라이언트가 감시하는 폴더를 이용해 연결하세요.³¹⁸

shortcuts CLI

macOS는 Monterey부터 Shortcuts용 정식 명령줄 인터페이스인 /usr/bin/shortcuts를 제공해 왔으며, shortcuts(1)과 Apple 사용자 가이드에 문서화되어 있어요.¹² 이 인터페이스에는 4개의 하위 명령이 있어요. 아래 내용은 모두 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

이름이나 식별자로 shortcut을 실행해요. “명령줄에서 shortcut을 실행하는 것은 Shortcuts 앱에서 실행하는 것과 다르지 않습니다.”¹ 이는 모든 action에 접근할 수 있는 동시에 모든 권한 요청도 그대로 표시된다는 뜻이에요(권한 참조).

Apple의 대표 예제는 JPEG 폴더를 대상으로 이미지 결합 shortcut을 실행해요.¹

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

CLI는 입력과 출력 양쪽에서 Unix 규약을 따라요. 종료 상태는 “shortcuts 명령이 성공적으로 실행되면 0으로, 오류가 발생하면 1로 종료됩니다.”¹ shortcut이 출력으로 끝나거나 중지 및 출력 action을 포함하면 출력 파이프도 작동해요.¹

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

문서에 명시된 한 가지 함정이 있어요. shortcuts run에 텍스트를 파이프로 입력하면 텍스트로 전달돼요. “파이프를 사용해 파일 경로를 전달하면 해당 경로는 텍스트로 처리됩니다. 입력이 파일 경로로 처리되도록 하려면 -i 플래그를 사용하세요.”¹

Apple이 제시한 설계 원칙 중 꼭 기억할 만한 내용도 있어요. “가장 효율적인 shortcut은 경고를 표시하거나 입력을 요청하지 않는 shortcut입니다. shortcut이 입력을 요청하면 명령줄 프로세스가 일시 중지되고 사용자 입력을 기다립니다.”¹ 헤드리스 환경에서는 이런 일시 중지가 곧 멈춤 상태예요. CLI에서 사용할 shortcut은 모든 매개변수를 입력으로 받도록 구성하세요.

shortcuts list

shortcut 이름을 한 줄에 하나씩 나열해요. --folders는 대신 폴더를 나열하고, -f <folder>는 특정 폴더로 범위를 제한해요. 어떤 폴더에도 속하지 않은 shortcut에는 “none”을 사용해요. --show-identifiers는 각 shortcut의 UUID를 덧붙여요.² 자동화에서는 식별자가 중요해요. 이름은 중복되거나 변경될 수 있지만 UUID는 그렇지 않아요. shortcuts run은 둘 다 사용할 수 있어요.²

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

shortcuts view

지정한 shortcut을 Shortcuts 편집기에서 열어요.² 도구 작업의 마지막 단계에서 유용해요. 실패한 shortcut을 감지한 스크립트가 해당 편집기를 바로 열도록 할 수 있어요.

shortcuts sign

배포할 .shortcut 파일에 서명해요. 공유 형식과 함께 5부에서 다뤄요.²

Shortcuts Events로 앱 스크립팅하기

세 번째 프로그래밍 인터페이스는 스크립팅 인터페이스예요. Mac의 Shortcuts에는 스크립팅 가능한 대상이 2개 등록되어 있어요. 하나는 Shortcuts 앱 자체이고, 다른 하나는 UI 없이 백그라운드에서 작동하는 Shortcuts Events예요. 번들 식별자는 com.apple.shortcuts.events이며 macOS 26.5에서 확인했어요.¹¹ 스크립팅 사전에는 이렇게 분리한 이유가 담겨 있어요. “Shortcuts 앱을 열지 않고 백그라운드에서 shortcut을 실행하려면 ‘Shortcuts’ 대신 ‘Shortcuts Events’에 지시하세요.”¹¹

사전은 작고 안정적이에요. shortcut에는 읽을 수 있는 name, subtitle, id, folder, color, icon, accepts input, action count 속성이 있고, 폴더에는 name과 id가 있어요. 유일한 동작은 run이며 선택 사항인 with input 매개변수와 실행 결과를 제공해요.¹¹

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"});

ScriptingBridge 또는 py-applescript를 통한 Python도 같은 인터페이스를 대상으로 해요. PyObjC의 ScriptingBridge에서는 SBApplication.applicationWithBundleIdentifier_("com.apple.shortcuts.events")가 앱 객체를 반환하며, 해당 객체의 shortcuts() 컬렉션은 위 사전의 구조를 그대로 반영해요.¹¹

CLI보다 이 방식을 선호할 만한 경우는 이미 AppleScript/JXA 컨텍스트 안에 있거나, 직렬화된 stdout 대신 shortcut의 결과를 네이티브 객체로 받으려 하거나, Apple Events를 보낼 수 있지만 셸 명령을 실행해서는 안 되는 앱에서 실행을 제어할 때예요. 호스트 프로세스가 Shortcuts Events에 첫 Apple Event를 보내면 macOS의 표준 자동화 동의 요청이 표시돼요(System Settings → Privacy & Security → Automation). 무인 실행 전에 이 권한 요청도 한 번 승인해야 해요.⁶

사전은 정리 작업에 필요한 접근 권한도 제공해요. 폴더와 shortcut 메타데이터를 읽을 수 있고 폴더 할당은 변경할 수 있으므로, UI를 건드리지 않고도 라이브러리 관리 작업인 목록 보고서나 폴더 감사를 스크립트로 처리할 수 있어요.¹¹

URL scheme

Shortcuts는 shortcuts:// URL scheme을 등록해요. 앱이 인수되기 전부터 이어진 기존 workflow://도 지원하며 macOS 26.5에서 확인했어요.¹⁹ URL은 런처, 링크 필드가 있는 메모 앱 등 URL을 열 수 있는 다른 앱에서 연동할 때 사용하는 경로예요. Apple의 안내는 명확해요. “Shortcuts 외부의 다른 앱에서 연동할 때만 URL로 shortcut을 실행해야 합니다.”⁹

shortcut 실행:⁹

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

• name(필수): 퍼센트 인코딩된 shortcut 이름이에요.
• input: text 또는 clipboard예요. text를 사용하면 text 매개변수 값이 shortcut의 입력이 돼요. clipboard를 사용하면 “Clipboard의 내용이 사용되며” text는 무시돼요.⁹

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

x-callback-url을 사용하면 왕복 작업의 응답을 처리할 수 있어요.²⁰

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

• 성공하면 x-success를 열고 shortcut의 텍스트 출력을 result 매개변수로 덧붙여요.
• 실패하면 x-error를 열고 errorMessage 매개변수를 전달해요.
• 사용자가 취소하면 x-cancel을 열며 출력은 제공하지 않아요.²⁰

셸에서는 open "shortcuts://run-shortcut?..."도 작동하지만, 셸에서는 shortcuts run을 사용하는 편이 좋아요. CLI는 URL 콜백을 거치지 않고 종료 코드와 출력을 직접 반환하기 때문이에요. Mac에서 이 scheme은 주로 앱 간 연동과 문서 안의 링크에 사용돼요.

공유 형식과 서명

Shortcuts는 2가지 방식으로 공유되며, 두 방식 모두 결국 신뢰 여부를 결정해야 해요.⁷

iCloud 링크. 앱에서 공유 → iCloud 링크 복사를 선택하세요. 링크가 있는 사람은 누구나 단축어를 자신의 보관함에 추가할 수 있어, 전 세계에 간편하게 공개할 때 적합해요. 링크를 전송한 순간부터 공개된 것으로 간주하세요.⁷

단축어 파일. 파일 → 내보내기를 선택하면 .shortcut 파일이 생성돼요(UTI com.apple.shortcut, macOS 26.5에서 확인).¹⁹⁷ 내보낼 때는 신뢰 범위를 반드시 선택해야 해요.

• 누구나: “누구나 단축어를 실행할 수 있어요.” Apple은 검증을 위해 단축어 사본을 받아요.⁷
• 나를 아는 사람: “연락처에 사용자가 등록된 사람만 단축어를 실행할 수 있어요.” 이 확인을 위해 사용자의 연락처 정보가 파일에 포함돼요.⁷

macOS 26.5의 shortcuts(1)에 따르면 CLI에도 같은 2가지 모드가 있으며 그 작동 방식도 명시돼 있어요. people-who-know-me는 “로컬에서 서명하지만 사용자의 기기 또는 연락처에 사용자의 연락처 정보가 등록된 사람만 단축어를 가져올 수 있고”, anyone은 “iCloud를 통해 공증하여 누구나 단축어를 가져올 수 있게 해요.”²

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

이 명령은 팀과 CI에서 단축어를 배포할 때 필요한 해답이에요. -m anyone으로 서명한 내보낸 단축어는 사용자를 전혀 모르는 사람도 문제없이 가져올 수 있어요. anyone 모드는 iCloud를 통해 공증하므로 빌드 파이프라인에 연결하기 전에 iCloud에 로그인된 세션과 네트워크 연결을 준비하세요.²

가져오기는 드래그 앤 드롭으로 처리할 수 있어요. .shortcut 파일을 이중 클릭하거나 앱으로 드래그하거나 Dock 아이콘에 놓으세요. .workflow 파일은 가져오는 과정에서 Automator 형식으로부터 변환돼요.¹⁵ Gallery 외부에서 공유된 Shortcuts에는 Apple이 명확하게 밝힌 주의 사항이 적용돼요. “Apple은 비공개로 공유된 단축어의 진위나 동작을 확인할 수 없어요.”⁶ 기업용 기기에는 별도의 방법이 있어요. Apple Configurator는 관리형 워크플로를 위한 Shortcuts 자동화를 지원해요.²¹

설정 → 고급에는 비공개로 공유된 연락처 제한 단축어의 가져오기를 제어하는 비공개 공유 스위치도 있어요. 스크립트 실행 허용 및 대량의 데이터 공유 허용 설정도 같은 곳에 있어요.⁶⁸ 받은 단축어를 가져올 수 없다면 대개 서명되지 않은 파일이거나, 연락처에 없는 사람이 보낸 연락처 제한 파일이거나, 비공개 공유가 비활성화된 경우예요.

App Intents: 앱에서 actions를 추가하는 방법

지금까지 살펴본 카탈로그의 모든 항목은 Apple이 제공해요. 보관함의 나머지 절반은 설치된 앱에서 가져오며, 2022년부터 이 과정에는 App Intents(iOS 16, macOS 13)라는 하나의 프레임워크가 사용돼요.¹³ 앱은 AppIntent를 준수하는 타입(동사 역할로, 매개변수와 perform() 메서드로 구성)을 정의하고, 선택적으로 AppEntity도 정의해요(명사 역할로, 식별자와 표시 표현을 갖춘 앱 콘텐츠의 타입 지정 요소). 이후 과정은 시스템이 처리해요. 같은 정의가 Shortcuts, Siri, Spotlight, 위젯, Apple Intelligence에 표시돼요. Shortcuts는 앱의 인텐트 스키마를 보여 주는 한 가지 방식이지 별도의 통합 기능이 아니에요.¹³⁴

앱이 Mac에 표시되는 방식에는 2가지 도입 수준이 중요해요.

• Actions: 숨겨지지 않은 모든 인텐트는 Shortcuts 편집기에서 앱 이름 아래에 action으로 표시되며, 이 가이드의 모든 항목과 조합할 수 있어요.
• App Shortcuts: AppShortcutsProvider로 감싼 인텐트는 앱을 설치하는 즉시 실행 가능한 단축어로 제공돼요. 사용자가 직접 조합할 필요가 없으며 Siri 실행 문구도 연결돼 있어요.¹³

프레임워크의 범위는 해마다 계속 넓어지고 있어요. Shortcuts와 Spotlight를 다룬 WWDC25 세션에서는 현재 Mac에 적용되는 규칙을 직접 설명해요. “인텐트를 macOS에서 사용할 수 있다면 Mac의 자동화에 포함해 실행할 수 있도록 Shortcuts에서도 사용할 수 있어요. macOS에 설치할 수 있는 iOS 앱도 여기에 포함돼요.”⁴ Apple silicon Mac에서 실행되는 iPhone 앱은 Mac 전용 코드를 한 줄도 작성하지 않아도 Mac 자동화에 actions를 제공해요.

같은 세션에서 제시한 Apple의 도입 지침을 요약하면 다음과 같아요. 콘텐츠를 “모델이 추론할 수 있어야 하는 핵심 속성”을 갖춘 엔티티로 노출하고(Use Model action이 이를 사용해요), 쿼리가 작동하도록 찾기 actions를 제공하고, 서식 있는 텍스트가 적합한 곳에서는 속성 문자열을 사용하고, 매개변수 요약을 읽기 쉽게 유지하세요.⁴

실제 서비스 앱에 App Intents를 적용한 경험을 바탕으로 정리한 인텐트 작성자용 설계 지침은 다음과 같아요.

• 인텐트는 API예요. 이름, 매개변수, 엔티티 식별자를 계약으로 다루세요. 엔드포인트 이름을 바꾸면 클라이언트가 망가지는 것처럼 이들을 변경하면 사용자의 단축어가 망가져요.
• 포그라운드보다 백그라운드가 나아요. 앱을 열지 않고 실행할 수 있는 인텐트는 자동화에 조합할 수 있지만, 포그라운드 전환이 필요한 인텐트는 사용자가 하던 작업을 방해해요. 두 유형을 의도적으로 분리하세요.⁴
• 반환 값은 파이프라인으로 이어져요. 엔티티나 값을 반환하는 인텐트는 Shortcuts 사용자가 다음 단계에 연결할 대상을 제공하지만, 아무것도 반환하지 않는 인텐트는 그래프의 막다른 지점이 돼요.

이 사이트의 App Intents 시리즈에서는 개발자 측면을 자세히 다뤄요. App Intents는 앱의 새로운 API예요(도입 근거와 실제 서비스 적용 과정), iOS 26의 App Intents 2.0(Visual Intelligence, 스니펫, 지연 속성), iOS 27의 App Intents(장시간 실행되는 백그라운드 인텐트, 동기화 가능한 엔티티, Spotlight 재색인), App Intents와 MCP 비교(같은 기능을 에이전트 도구로도 제공해야 하는 시점)를 참고하세요.

Spotlight와 자동화에서 인텐트 실행하기

macOS Tahoe는 인텐트가 실행되는 범위를 확장했으며, 새로 추가된 2가지 기능은 Mac에서 “App Intents 도입”으로 얻을 수 있는 이점을 바꿨어요.⁴

Spotlight는 인텐트를 그 자리에서 실행해요. “올해부터 Mac의 Spotlight에서 앱의 actions를 직접 실행할 수 있어요. Shortcuts에서와 마찬가지로 App Intents를 도입하면 앱의 actions를 Spotlight에 표시할 수 있어요.”⁴ 요구 사항은 구체적이어서 다음과 같이 점검할 수 있어요.

1. 매개변수 요약(“앱 인텐트의 기능을 자연어로 짧게 표현한 설명”)에는 “기본값이 없는 모든 필수 매개변수가 포함되어야 해요.”⁴
2. 인텐트가 검색 노출을 거부하도록 설정되어 있으면 안 돼요. isDiscoverable이 false이거나 assistantOnly가 true이면 Spotlight에서 제외돼요.⁴
3. 제안과 검색은 엔티티 계층에서 제공돼요. 선택기에 표시하려면 추천 엔티티 또는 열거 가능한 엔티티 쿼리를 구현하고, 입력과 동시에 검색하려면 엔티티 문자열 쿼리 또는 색인된 엔티티를 구현하세요.⁴

자동화는 인텐트를 사용자 없이 실행해요. Tahoe 자동화는 단축어를 실행하고 단축어는 인텐트를 실행하므로, 이제 폴더 변경이나 드라이브 마운트가 사용자가 없는 상태에서도 앱의 인텐트를 호출할 수 있어요.⁴ 따라서 인텐트 작성자는 앞 섹션에서 제시한 기준을 더 엄격하게 적용해야 해요. 포그라운드 사용자가 있다고 가정하는 인텐트는 UI를 표시하거나 확인을 요구하기 때문에 즉시 실행 자동화 안에서 조용히 실패해요. 각 인텐트가 무인 실행에 적합한지 점검하세요. 화면을 보는 사람이 아무도 없을 때 어떻게 작동하나요?

이 2가지 기능을 종합하면 Apple의 조용한 아키텍처 선언이 드러나요. Mac에서 기능의 단위는 앱 창이 아니라 인텐트예요. Spotlight는 대화형 호출자이고, 자동화는 무인 호출자이며, Shortcuts는 둘 사이의 구성 계층이에요.

스크립트와 에이전트에서 Shortcuts 실행하기

Shortcuts는 에이전트 및 스크립트 아키텍처에서 고유한 역할을 해요. 외부 코드가 Mac 기능을 호출할 때 최소 권한을 유지하면서 사용자가 가장 쉽게 감사할 수 있는 방식이에요. 셸에 접근할 수 있는 AI 에이전트는 대부분의 작업을 직접 처리할 수 있지만, 단축어를 통해 작업을 실행하면 일반 셸에는 없는 특성을 얻을 수 있어요. 작업을 사용자가 정의하고 편집할 수 있으며, 권한은 단축어별로 부여되고 클릭 한 번으로 취소할 수 있고, 영향을 미치는 범위도 편집기에서 확인할 수 있어요.⁶ 단축어 계층은 사용자가 관리하고 에이전트가 호출하는 기능 카탈로그라고 생각하면 돼요.

이 모든 기능을 사용하려면 반드시 충족해야 하는 조건이 하나 있어요. CLI에는 로그인된 GUI 세션이 필요해요. list를 포함한 모든 shortcuts 하위 명령은 사용자의 Aqua 세션에 있는 헬퍼 애플리케이션과 통신하며, 해당 세션이 없으면 “Couldn’t communicate with a helper application” 오류와 함께 실패해요(macOS 26.5에서 확인). SSH 전용 세션, 헤드리스 CI 실행기, launch daemon은 이 제약에 걸려요. 에이전트와 예약 호출은 로그인된 사용자 세션 안에서 실행하세요. 즉, daemon이 아니라 launchd agent를 사용해야 해요.

에이전트 관점에서 본 호출 규약:¹²

구조화된 데이터는 텍스트로 경계를 넘어요. 실용적인 방식은 stdin/stdout을 통해 JSON을 전달하는 거예요. 호출자가 JSON 문서를 파이프로 입력하고(-i -), 단축어는 Get Dictionary from Input으로 이를 파싱해 작업을 수행한 뒤, Stop and Output으로 딕셔너리를 텍스트 형태로 반환해요.¹¹⁶ 이렇게 하면 단축어가 문서화된 스키마를 갖춘 타입 함수처럼 동작해요. 각 단축어의 예상 입력 및 출력 형식을 설명하는 README를 해당 단축어를 호출하는 에이전트 설정과 함께 관리하세요.

시간 제한은 호출자가 처리해야 해요. 알림을 표시하는 단축어는 CLI 프로세스를 무기한 일시 중지할 수 있으므로,¹ 무인 호출자는 항상 시간 제한을 적용하고 제한 시간 초과를 실패로 처리해야 해요.

# 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"

무인 실행 전에 권한을 미리 승인하세요. 각 단축어를 대화형으로 한 번 실행하고 프롬프트에서 Always Allow를 선택하세요. 에이전트나 launchd 작업에서 호출하기 전에 터미널에서 프롬프트 없이 실행되는지도 확인하세요.⁶¹ 미리 승인하는 권한의 종류는 권한 섹션에서 설명해요.

호출자 유형에 맞는 진입점을 선택하세요. 셸을 사용할 수 있는 호출자(에이전트, CI, launchd agents, Makefiles 등)는 모두 로그인된 세션 안에서 CLI를 사용해요. Apple Event 환경(AppleScript 앱, PyObjC daemons)은 Shortcuts Events를 사용하며 네이티브 반환 값을 받을 수 있어요.¹¹ 샌드박스 환경이나 URL만 사용할 수 있는 환경에서는 shortcuts://run-shortcut과 x-callback을 사용해 결과를 받아요.⁹²⁰ 세 방식 모두 같은 단축어를 실행하며 전송 방식만 달라요.

반대 방향도 가능해요. 단축어를 에이전트의 프런트엔드로 사용할 수 있어요. 키보드 단축키나 메뉴 막대 슬롯이 지정된 단축어로 컨텍스트(선택 항목, 클립보드, 맨 앞의 앱)를 수집하고, Run Shell Script에서 에이전트 CLI를 호출해 컨텍스트를 전달한 다음 결과를 표시할 수 있어요. 이렇게 하면 운영 체제의 입력 인터페이스를 기반 도구의 UI로 활용할 수 있어요.¹⁰¹⁷

권한과 동의(TCC)

Shortcuts는 동의를 우선하는 macOS 보안 모델을 따르며, 논리 오류가 아닌 자동화 실패는 결국 이 모델에서 원인을 찾게 돼요. 이 모델은 4개 계층으로 구성돼요. 어느 계층에서 프롬프트가 표시되는지 알면 해결 방법도 명확해져요.

1. 단축어별 데이터 접근 동의. 단축어가 보호된 리소스에 처음 접근하면 Shortcuts에서 다음과 같이 안내해요. “If a Privacy dialog appears requesting access to data, choose Allow Once, Always Allow, or Don’t Allow.” Always Allow는 “다음에 이 단축어를 실행할 때 Shortcuts 앱에서 접근 권한을 다시 묻지 않음”을 의미해요.⁶ 권한은 단축어별, 리소스별로 부여되며 직접 확인할 수 있어요. 각 단축어의 세부 정보 패널에 있는 Privacy 탭에서 개별 권한을 취소할 수 있고, “To remove access to all data for this shortcut, click Reset Privacy.” 안내에 따라 모든 권한을 초기화할 수도 있어요.⁶

2. 스크립트 실행 관문. 5개의 스크립트 actions는 Settings → Advanced → Allow Running Scripts가 활성화된 경우에만 실행돼요(위의 정확한 목록).⁸ 이 설정은 단축어별 설정이 아니라 전역 설정이에요. 핫 폴더 스크립트 하나를 위해 활성화하더라도 가져온 모든 단축어에서 스크립트를 실행할 수 있게 되므로, 가져온 단축어는 실행 전에 내용을 확인해야 해요.⁶

3. 시스템 TCC 프롬프트. 운영 체제의 보호 영역에 접근하는 actions(파일 및 폴더, 다른 앱을 스크립팅하기 위한 Automation/Apple Events, 입력 제어를 위한 Accessibility)는 System Settings → Privacy & Security에서 관리하는 시스템 수준의 대화 상자를 표시해요. 권한은 해당 작업을 담당하는 프로세스에 연결돼요. 따라서 동일한 단축어라도 앱, CLI, 자동화에서 각각 다르게 동작할 수 있어요. 실행 환경이 다르면 권한도 별도로 부여되기 때문이에요.⁶

4. 자동화 실행 정책. 각 자동화의 Run Immediately와 Run After Confirmation 설정에 따라 트리거 자체에 사람의 확인이 필요한지가 결정돼요.¹⁸

이에 따라 다음 운영 규칙을 지켜야 해요.

• 아무도 보고 있지 않은 환경에서는 프롬프트를 처리할 수 없어요. 헤드리스 환경(SSH 세션, CI 실행기, 에이전트)에도 CLI 섹션의 첫 번째 규칙이 적용돼요. 응답하지 않은 동의 대화 상자는 작업을 무기한 일시 중지해요.¹ 대화형으로 미리 승인하세요.
• Reset Privacy는 초기 상태에서 디버깅할 때 유용해요. 단축어를 편집한 뒤 오작동한다면 권한을 초기화하고 대화형으로 다시 실행하세요. 필요한 프롬프트가 순서대로 다시 표시돼요.⁶
• 가져온 단축어는 내용을 확인해야 해요. Apple은 “Anyone”으로 서명된 단축어를 검증하지만, 비공개로 공유된 단축어의 진위나 동작은 검증할 수 없어요.⁶⁷ Privacy 탭에서는 단축어에 부여된 권한을 확인할 수 있고, 편집기에서는 단축어가 수행하는 작업을 확인할 수 있어요. 둘 다 확인하는 데 1분이면 충분해요.

문제 해결

빠른 참조 카드

# 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

체크리스트. 무인 실행 준비가 완료된 단축어: 알림이나 Ask Each Time 매개변수가 없고, Always Allow로 동의를 미리 승인했으며, UUID로 호출하고, 호출자가 시간 제한을 적용하며, Stop and Output으로 끝나요.¹⁶ 배포 준비가 완료된 파일: 내보내기를 완료하고 -m anyone으로 서명했으며 입력 규약을 문서화했어요.²⁷

FAQ

Terminal에서 Mac shortcut을 실행하려면 어떻게 하나요? shortcuts run "Shortcut Name"을 사용하세요. 입력 파일에는 선택적으로 -i(또는 stdin에는 -)를, 출력에는 -o(또는 stdout에는 -)를, Uniform Type Identifier에는 --output-type을 사용할 수 있습니다. 이 명령은 성공하면 0, 오류가 나면 1로 종료하므로 다른 Unix 도구처럼 &&, if, make와 함께 조합할 수 있습니다.¹²

macOS에도 마침내 iOS 같은 Shortcuts 자동화가 생겼나요? 네. macOS Tahoe (26)부터 사용할 수 있습니다. 트리거에는 시간, 알람, 이메일, 메시지, 폴더 변경, 외장 드라이브, 디스플레이, Wi-Fi, Bluetooth, 배터리 수준, 충전기, 앱 열기/종료, Focus, Stage Manager가 포함되며, 각각 즉시 실행하거나 확인 후 실행하도록 설정할 수 있습니다.³⁴¹⁸

shortcuts sign -m anyone은 실제로 무엇을 하나요? iCloud를 통해 shortcut 파일을 공증하므로 누구나 가져올 수 있게 합니다. 기본 모드인 people-who-know-me는 로컬에서 서명하며, 본인 기기와 Contacts에 본인의 연락처 정보가 있는 사람으로 가져오기를 제한합니다.²

앱은 Mac의 Shortcuts에 자체 actions를 어떻게 추가하나요? App Intents 프레임워크를 채택하면 됩니다. Intents는 자동으로 Shortcuts actions로 표시되며, AppShortcutsProvider를 사용하면 별도 설정 없이 App Shortcuts가 앱과 함께 제공됩니다. macOS에서 사용할 수 있는 intents는 Spotlight와 Tahoe 자동화 안에서도 실행되며, Apple silicon Mac에 설치된 iOS 앱의 intents도 포함됩니다.¹³⁴

스크립트나 AI agent는 shortcuts를 어떻게 호출해야 하나요? CLI을 사용하세요. shortcuts list --show-identifiers로 찾아 UUID로 호출하고, JSON은 stdin으로 전달하며 결과는 stdout에서 읽으세요. 프롬프트를 표시하는 shortcut은 무한히 멈춰 있을 수 있으므로 모든 호출을 timeout으로 감싸야 합니다(macOS에는 timeout(1)이 없으므로 coreutils의 gtimeout 또는 사용하는 언어의 프로세스 timeout을 사용하세요). 무인 실행 전에 각 shortcut의 권한 프롬프트를 대화형으로 미리 승인하세요. AppleScript 컨텍스트에서는 앱을 열지 않고 실행하려면 Shortcuts Events를 대상으로 지정하세요.¹²¹¹

Shortcuts가 Automator를 대체할 수 있나요? 대부분의 워크플로에서는 가능합니다. Apple은 Shortcuts를 Mac 자동화의 미래라고 부르며, 대부분의 .workflow 파일을 직접 가져오는 변환기도 만들었습니다. Automator는 계속 제공되고 기존 워크플로도 계속 실행되므로, 마이그레이션은 마감 기한이 아니라 선택 사항입니다.⁵¹⁴¹⁵

변경 로그

참고 자료