부록 B. 액션 타입 레퍼런스

15분 읽기

부록 B. 액션 타입 레퍼런스

Keyboard Maestro에서 사용할 수 있는 주요 액션 타입을 카테고리별로 정리했습니다. 각 액션 타입의 XML 내부 이름(MacroActionType), 한국어명, 설명, 그리고 이 책에서 해당 액션이 사용된 챕터를 함께 표기했습니다.

액션 타입 읽는 법

Keyboard Maestro의 매크로는 내부적으로 XML(plist) 형식으로 저장됩니다. 각 액션은 MacroActionType이라는 키로 식별되며, 이 값이 액션의 종류를 결정합니다.

<dict>
    <key>MacroActionType</key>
    <string>ExecuteShellScript</string>
    <key>Path</key>
    <string>/bin/bash</string>
    <key>Text</key>
    <string>echo "Hello, World!"</string>
</dict>

위 예시에서 MacroActionType이 ExecuteShellScript이므로, 이 액션은 셸 스크립트를 실행하는 액션입니다. .kmmacros 파일을 텍스트 에디터로 열어 보면 이 구조를 직접 확인할 수 있습니다.

액션 타입의 명명 규칙:

  • 동사 + 목적어 형태가 일반적입니다: ExecuteShellScript, SetVariableToText, ActivateApplication
  • 일부 액션은 별칭(alias)이 있습니다: SelectMenuItem과 MenuSelect는 같은 동작을 가리킵니다
  • KM 에디터의 UI에 표시되는 이름과 내부 MacroActionType 값이 다를 수 있으므로, XML을 직접 편집하거나 분석할 때는 이 레퍼런스를 참고하십시오

이 책의 70개 매크로에서 실제로 사용된 기술 통계:

기술 사용 매크로 수
조건 분기 (IfThenElse) 33
셸 스크립트 (ExecuteShellScript) 23
변수 (SetVariableToText 등) 20
AppleScript (ExecuteAppleScript) 12
JavaScript (ExecuteJavaScript 등) 11
서브매크로 (ExecuteMacro) 8
반복 (For, Until) 5

UI 조작

UI 조작 액션은 앱의 메뉴, 버튼, 윈도우, 키보드 입력 등 사용자 인터페이스 요소를 프로그래밍 방식으로 제어합니다.

액션 타입 한국어명 설명 사용 예시 (챕터)
SelectMenuItem 메뉴 선택 앱 메뉴 항목을 클릭합니다 Chrome 프로필 전환에서 "파일 > 새로운 윈도우 > 새로운 공부용 윈도우" 선택 (ch04), NotebookLM 매크로에서 "프로필 > 재식 (회사)" 선택 (ch14)
PressButton 버튼 클릭 UI 버튼을 접근성(Accessibility) 정보를 기반으로 클릭합니다 NotebookLM에서 "Add source" 버튼 클릭 (ch14)
ManipulateWindow 윈도우 조작 창의 위치, 크기를 변경하거나 최소화/최대화합니다 모니터별 윈도우 배치: Main/Second/Third Monitor 매크로에서 MoveAndResize 동작 (ch06), 크롬 윈도우 위치 설정 서브매크로 (ch11)
SimulateKeystroke 키 입력 시뮬레이션 가상으로 키보드 입력을 발생시킵니다 모니터 매크로에서 윈도우 배치 후 전체화면 단축키 전송 (ch06), Chrome 주소창 영문 변환 (ch03), CursorChatSubmit (ch15)
BringWindowsForward 윈도우 앞으로 특정 앱의 모든 윈도우를 전면으로 가져옵니다 크롬 윈도우 위치 설정 서브매크로에서 윈도우 정렬 시 사용 (ch11)
ClickAtFoundImage 이미지 클릭 화면에서 이미지를 찾아 해당 위치를 클릭합니다 --
MoveOrClickMouse 마우스 이동/클릭 좌표 기반으로 마우스를 이동하거나 클릭합니다 마우스 커서 화면 중앙으로 가져오기 (ch06)
ScrollWheel 스크롤 마우스 휠 스크롤을 시뮬레이션합니다 --
SetActionDelay 액션 딜레이 설정 이후 액션들 사이의 기본 대기 시간을 설정합니다 Chrome 프로필 전환 (ch04), Gemini Google Docs 저장 (ch14)

텍스트

텍스트 액션은 키보드 입력, 클립보드 조작, 텍스트 검색/치환 등 텍스트 처리와 관련된 작업을 수행합니다.

액션 타입 한국어명 설명 사용 예시 (챕터)
InsertText 텍스트 입력 텍스트를 타이핑 또는 붙여넣기 방식으로 입력합니다 NotebookLM에서 URL 입력 (ch14)
InsertTextByPasting 붙여넣기로 입력 클립보드를 경유하여 텍스트를 입력합니다. 특수 문자나 긴 텍스트에 적합합니다 --
InsertTextByTyping 타이핑으로 입력 키 하나하나를 시뮬레이션하여 텍스트를 입력합니다 --
SetClipboardToText 클립보드 설정 클립보드의 내용을 지정된 텍스트로 변경합니다 ChatGPT 마크다운 복사 (ch09)
FilterClipboard 클립보드 필터 클립보드에 저장된 텍스트를 변환하거나 가공합니다 --
SearchAndReplace 검색/치환 변수나 클립보드의 텍스트에서 패턴을 찾아 치환합니다 --

스크립팅

스크립팅 액션은 외부 스크립트 언어를 Keyboard Maestro 안에서 실행할 수 있게 합니다. 70개 매크로 중 가장 빈번하게 사용되는 카테고리입니다.

액션 타입 한국어명 설명 사용 예시 (챕터)
ExecuteShellScript 셸 스크립트 실행 bash/zsh 스크립트를 실행합니다. %Variable% 토큰으로 KM 변수에 접근 가능합니다 바탕화면 파일 숨기기/보이기 (ch07), 전원 제어 매크로 (ch07), Cron Job의 get-place-info/get-naver-points (ch12), Youtube 관심없음/채널 차단 (ch09), Obsidian 자동 커밋 (ch08), npm 글로벌 패키지 업데이트 (ch12), 새 텍스트 파일 생성 (ch08)
ExecuteAppleScript AppleScript 실행 AppleScript 코드를 실행합니다. macOS 앱 간 통신에 강점이 있습니다 Quicklink 매크로에서 Chrome 프로필별 URL 열기 (ch05), Slack 상태 변경에서 Raycast 딥링크 호출 (ch10), Google Meet 셋업 (ch08), Gemini 탭 URL 수집 (ch14), Finder 현재 경로 가져오기 (ch08), Youtube 프로필 영상 재생 (ch09)
ExecuteJavaScriptForAutomation JXA 실행 JavaScript for Automation을 실행합니다. AppleScript의 대안입니다 --
ExecuteJavaScript 브라우저 JS 실행 Chrome 또는 Safari 탭에서 JavaScript를 실행합니다 Chrome PIP 모드 전환 (ch03), Gemini 공유/내보내기 버튼 클릭 (ch14), NotebookLM 프로젝트 목록 추출 (ch14), Youtube 재생목록 삭제 (ch09), ChatGPT 마크다운 변환 (ch09)
ExecuteSwiftScript Swift 실행 Swift 코드를 실행합니다 --

참고: ExecuteShellScript의 결과를 KM 변수에 저장하려면 스크립트의 표준 출력(stdout)을 사용합니다. 셸 스크립트 액션의 "Save results to variable" 옵션을 설정하면 출력값이 지정한 변수에 자동 저장됩니다.

흐름 제어

흐름 제어 액션은 매크로의 실행 순서를 조건, 반복, 대기 등으로 제어합니다. 33개 매크로에서 조건 분기가 사용될 만큼, 가장 핵심적인 카테고리입니다.

액션 타입 한국어명 설명 사용 예시 (챕터)
IfThenElse 조건 분기 if/else 조건문입니다. 조건을 만족하면 Then 블록, 아니면 Else 블록을 실행합니다 Chrome PIP에서 Safari/Chrome 분기 (ch03), 프로필 전환에서 현재 브라우저 판별 (ch04), Cron Job에서 컴퓨터 이름 확인 (ch12), 로그인 시 주말/평일 분기 (ch13), 모니터 접속 시 모니터 수 분기 (ch13), 헤드폰/모니터 분기 (ch10)
SwitchCase 다중 분기 switch/case 문입니다. 하나의 값에 대해 여러 경우를 분기합니다 --
For 반복(항목별) 컬렉션(줄바꿈으로 구분된 목록)을 순회하며 반복합니다 Gemini Google Docs 저장에서 탭 목록 순회 (ch14)
Until 반복(조건충족까지) 조건이 충족될 때까지 반복합니다 크롬 윈도우 위치 설정에서 특정 윈도우가 나타날 때까지 반복 (ch11)
Repeat 반복 지정 횟수만큼 반복합니다 --
While 반복(조건) 조건이 참인 동안 반복합니다 --
Pause 일시 정지 지정된 시간(초) 동안 대기합니다 로그인 서브루틴에서 앱 실행 후 1초 대기 (ch11), Gemini 저장에서 버튼 클릭 사이 0.1초 대기 (ch14)
PauseUntil 조건 대기 특정 조건(앱 실행, 윈도우 출현 등)이 충족될 때까지 대기합니다 로그인 서브루틴에서 Chrome이 완전히 실행될 때까지 대기 (ch11)
BreakFromLoop 반복 탈출 현재 반복을 즉시 중단하고 반복문 밖으로 이동합니다 --
CancelMacro 매크로 취소 현재 실행 중인 매크로를 중단합니다 --
CancelAllMacros 전체 취소 실행 중인 모든 매크로를 중단합니다 Cancel All Macros 유틸리티 (ch06)
TryCatch 예외 처리 try/catch 방식으로 에러를 처리합니다 --
Throw 에러 발생 의도적으로 에러를 발생시켜 TryCatch에서 잡을 수 있게 합니다 --
Group 그룹 여러 액션을 하나로 묶습니다. 접기/펼치기가 가능하여 매크로 정리에 유용합니다 --
Comment 주석 실행되지 않는 설명입니다. 매크로의 의도를 문서화합니다 로그인 서브루틴에서 단계 설명 (ch11)
Semaphore 세마포어 동시 실행을 제어합니다. 같은 리소스에 접근하는 매크로의 충돌을 방지합니다 --

변수

변수 액션은 Keyboard Maestro 변수의 생성, 수정, 삭제를 담당합니다. 20개 매크로에서 변수를 활용하고 있습니다.

액션 타입 한국어명 설명 사용 예시 (챕터)
SetVariableToText 변수 설정 변수에 텍스트 값을 할당합니다. %Token% 형태의 토큰을 사용할 수 있습니다 computerName 변수에 %MacName% 토큰 저장 -- Cron Job/Slack 상태/헤드폰/모니터 등 다수 매크로에서 공통 사용 (ch10, ch12, ch13), varDate에 %ICUDateTime%EEE%로 요일 저장 (ch13)
SetVariableToCalculation 변수 계산 수식의 결과를 변수에 저장합니다 --
FilterVariable 변수 필터 변수의 값을 변환합니다 (대소문자, 트림, 정규식 등) --
DeleteVariable 변수 삭제 변수를 제거합니다 --
SetDictionaryValue 사전 값 설정 Dictionary(사전) 타입 변수의 키-값 쌍을 설정합니다 --
PromptForUserInput 사용자 입력 대화상자를 표시하여 사용자에게 값을 입력받습니다 NotebookLM에서 프로젝트 목록 중 선택 (ch14)

변수 명명 규칙: KM 변수는 Local__로 시작하면 해당 매크로 내에서만 유효한 지역 변수가 됩니다. Instance__로 시작하면 매크로의 각 실행 인스턴스별로 독립된 값을 갖습니다. 접두사가 없으면 전역 변수로, 모든 매크로에서 공유됩니다.

앱 제어

앱 제어 액션은 애플리케이션의 실행, 종료, 전환, 파일/URL 열기 등을 수행합니다.

액션 타입 한국어명 설명 사용 예시 (챕터)
ActivateApplication 앱 활성화 앱을 전면(foreground)으로 가져옵니다. 앱이 실행 중이 아니면 실행합니다 로그인 서브루틴에서 Chrome, Slack 활성화 (ch11), 크롬 윈도우 위치 설정에서 Chrome 활성화 (ch11), NotebookLM에서 Chrome 활성화 (ch14)
QuitApplication 앱 종료 앱을 종료합니다 --
LaunchApplication 앱 실행 앱을 시작합니다 시스템 설정 앱 실행 (ch06)
OpenFile 파일 열기 파일이나 폴더를 기본 앱으로 엽니다 Finder Download 매크로 (ch08)
OpenURL URL 열기 웹 주소를 기본 브라우저로 엽니다 Quicklink 매크로: gdrive, gcalendar, gmail (ch05)
SwitchToApplication 앱 전환 지정된 앱으로 전환합니다 --
SafariControl Safari 제어 Safari 브라우저의 탭, 윈도우 등을 제어합니다 Chrome 프로필 전환에서 Safari 탭 조작 (ch04), NotebookLM에서 Safari 탭 전환 (ch14)

서브매크로

서브매크로 액션은 다른 매크로를 호출하여 재사용 가능한 모듈로 활용합니다. 8개 매크로에서 사용되며, 특히 업무 환경 설정 관련 매크로에서 핵심적인 역할을 합니다.

액션 타입 한국어명 설명 사용 예시 (챕터)
ExecuteMacro 매크로 실행 UID로 다른 매크로를 호출합니다. 가장 일반적인 서브매크로 호출 방식입니다 "99. Sub - 업무 프로그램 위치 저장 및 실행"에서 크롬 윈도우/Slack 윈도우 위치 설정 서브매크로 호출 (ch11), "99. Sub - 로그인"에서 업무 프로그램 위치 서브매크로 호출 (ch11), 로그인 시 주말/평일 분기에서 로그인 서브루틴 호출 (ch13), Finder settings에서 설정 서브매크로 호출 (ch08)
ExecuteMacroByName 이름으로 매크로 실행 매크로 이름 문자열로 호출합니다. 동적 호출에 사용됩니다 --
ExecuteSubroutine 서브루틴 실행 서브루틴 매크로를 호출합니다. 매개변수 전달이 가능합니다 --

서브매크로 호출 체인 예시 (ch11, ch13):

로그인 시 주말/평일 분기
  --> 99. Sub - 로그인
      --> 99. Sub - 업무 프로그램 위치 저장 및 실행
          --> 99. Sub - 크롬 윈도우 위치 설정
              --> Utility - Third Monitor
              --> Utility - Second Monitor
          --> 99. Sub - Slack 윈도우 위치 설정
              --> Utility - Main Monitor

알림

알림 액션은 사용자에게 매크로의 실행 상태나 결과를 시각적/청각적으로 전달합니다.

액션 타입 한국어명 설명 사용 예시 (챕터)
Notification 알림 macOS 알림 센터에 알림을 표시합니다 --
DisplayAlert 경고 대화상자 경고/확인 대화상자를 표시합니다. 사용자의 확인/취소 응답을 받을 수 있습니다 --
DisplayText 텍스트 표시 화면에 텍스트 오버레이를 표시합니다. 일정 시간 후 자동으로 사라집니다 --
PlaySound 소리 재생 효과음 파일을 재생합니다 --
SpeakText 음성 출력 macOS TTS(Text-to-Speech)로 텍스트를 음성으로 읽어줍니다 --
SystemBeep 시스템 비프 기본 시스템 알림음을 재생합니다 --

시스템

시스템 액션은 macOS 시스템 수준의 설정과 상태를 제어합니다.

액션 타입 한국어명 설명 사용 예시 (챕터)
SetSystemClipboard 시스템 클립보드 시스템 클립보드를 직접 조작합니다 --
SetMouseLocation 마우스 위치 마우스 커서를 지정 좌표로 이동합니다 마우스 커서 화면 중앙으로 가져오기 (ch06)
SetAudioDevice 오디오 장치 설정 오디오 입출력 장치를 변경합니다 헤드폰/모니터 분기 매크로에서 오디오 출력 장치 전환 (ch10)
ScreenCapture 화면 캡처 스크린샷을 촬영합니다 --
SetBrightness 밝기 설정 화면 밝기를 조절합니다 --
SetVolume 볼륨 설정 시스템 볼륨을 조절합니다 --
SystemSleep 시스템 절전 Mac을 잠자기 모드로 전환합니다 --

파일

파일 액션은 파일 시스템의 파일을 읽고, 쓰고, 이동하고, 삭제하는 작업을 수행합니다.

액션 타입 한국어명 설명 사용 예시 (챕터)
ReadFile 파일 읽기 파일의 내용을 변수로 읽어옵니다 --
WriteFile 파일 쓰기 변수나 텍스트를 파일에 씁니다 --
AppendToFile 파일 추가 파일 끝에 내용을 추가합니다 --
MoveFile 파일 이동 파일을 다른 위치로 이동하거나 이름을 변경합니다 --
DeleteFile 파일 삭제 파일을 제거합니다 --
RenameFile 파일 이름 변경 파일명을 변경합니다 --
File 파일 조작 파일 관련 범용 액션입니다 새 텍스트 파일 생성 매크로에서 Finder에 파일 표시 (ch08)

참고: 셸 스크립트 내에서 파일을 조작하는 것이 더 유연한 경우가 많습니다. 이 책의 매크로들은 대부분 ExecuteShellScript 안에서 파일 작업을 수행합니다.

Mermaid 흐름도 매핑

이 책에서는 매크로의 액션 체인을 Mermaid 순서도로 시각화합니다. 각 액션 타입이 흐름도에서 어떤 노드 형태로 표현되는지 아래 표를 참고하십시오.

액션 카테고리 Mermaid 노드 형태 구문 예시
시작/끝 타원 (stadium) ([텍스트]) ([트리거: ⌃⌥⌘K])
조건 분기 마름모 (rhombus) {텍스트} {헤드폰 연결?}
스크립팅 직사각형 (rectangle) [텍스트] [셸 스크립트: crawl.sh 실행]
UI 조작 둥근 직사각형 (rounded) (텍스트) (메뉴 선택: 파일 > 새 윈도우)
반복 서브그래프 + 루프 화살표 subgraph Loop subgraph 탭 목록 순회
서브매크로 이중 테두리 (subroutine) [[텍스트]] [[99. Sub - 로그인]]
일시 정지 사다리꼴 (trapezoid) [/텍스트/] [/1초 대기/]
변수 설정 평행사변형 (parallelogram) [/텍스트\\] [/computerName = %MacName%\\]
알림 비대칭 (asymmetric) >텍스트] >알림: 완료]
주석 점선 테두리 (dashed) ---텍스트--- 흐름도에 표시하지 않음

Mermaid 흐름도 작성 예시:

다음은 "Youtube - 특정 프로필로 영상 재생하기" 매크로(ch09)의 흐름도입니다.

flowchart TD A(["트리거: ⌃1"]) --> B[/"computerName = %MacName%"\] B --> C["셸 스크립트: 현재 URL 추출"] C --> D{"컴퓨터 이름 일치?"} D -- Yes --> E["AppleScript: 지정 프로필로 URL 열기"] D -- No --> F(["종료"]) E --> F

흐름도 작성 원칙:

  1. 트리거는 항상 ([트리거: ...]) 형태의 타원으로 시작합니다
  2. 조건 분기는 마름모에 Yes/No 라벨을 붙입니다
  3. 서브매크로 호출은 이중 테두리로 구분하여 별도 매크로임을 나타냅니다
  4. 반복문은 subgraph로 감싸서 반복 범위를 명확히 합니다
  5. 각 노드의 텍스트는 실제 동작을 간결하게 요약합니다

액션 타입 빈도 분석

아래 표는 이 책의 70개 매크로에서 실제로 등장하는 액션 타입을 빈도순으로 정리한 것입니다.

순위 액션 타입 등장 횟수 (대략) 주요 용도
1 IfThenElse 33+ 컴퓨터 이름 확인, 앱 상태 분기, 주말/평일 분기
2 ExecuteShellScript 23+ 외부 스크립트 실행, 시스템 명령, 파일 조작
3 SetVariableToText 20+ computerName, varDate 등 환경 정보 저장
4 ExecuteAppleScript 12+ 앱 간 통신, Raycast 딥링크, Chrome 제어
5 ExecuteJavaScript 11+ 브라우저 DOM 조작, 버튼 클릭, 데이터 추출
6 SimulateKeystroke 10+ 단축키 전송, 윈도우 배치 후 전체화면
7 ExecuteMacro 8+ 서브매크로 호출 체인
8 Pause 7+ 앱 실행/UI 반응 대기
9 ManipulateWindow 5+ 윈도우 위치/크기 조정
10 ActivateApplication 5+ Chrome, Slack 등 앱 활성화

이 통계에서 알 수 있듯이, 실전 매크로에서는 조건 분기 + 스크립팅 + 변수의 조합이 압도적으로 많이 사용됩니다. 특히 SetVariableToText로 %MacName% 토큰을 읽고, IfThenElse로 컴퓨터를 식별한 뒤, 스크립트를 실행하는 패턴은 여러 Mac을 사용하는 환경에서 반복적으로 나타나는 핵심 패턴입니다.