명령줄 (snapzy)
snapzy 명령으로 터미널, 스크립트, AI 에이전트에서 디스플레이, 창 또는 영역을 캡처하세요. 오버레이도 클릭도 필요 없으며, 파일 경로, JSON, 종료 코드를 돌려받습니다.
개요
Snapzy는 snapzy 명령을 함께 제공하므로 AI 에이전트(Claude Code, Cursor, Codex 등), 셸 스크립트, 그리고 사용자의 터미널에서 마우스를 건드리지 않고 스크린샷을 찍을 수 있습니다. 각 명령은 파일 경로, JSON 메타데이터, 의미 있는 종료 코드를 반환합니다.
- 씬 클라이언트.
snapzy는 비공개 Unix 소켓을 통해 실행 중인 Snapzy 앱과 통신합니다. 캡처는 Snapzy가 수행하므로 화면 기록 권한은 Snapzy에만 있으면 됩니다 — 터미널이나 에이전트에는 이 권한이 필요하지 않습니다. - Snapzy를 자동으로 실행. Snapzy가 실행 중이 아니면 명령이 백그라운드에서 앱을 열고 준비될 때까지 기다립니다(온보딩을 마친 뒤에는 스플래시 화면이 표시되지 않습니다). 대신 실패하도록 하려면
--no-launch를 전달하세요. - 헤드리스. 명령줄 캡처는 빠른 접근(Quick Access)을 열지 않고, 클립보드를 건드리지 않으며, 기록 항목을 추가하지 않고, 프리셋을 적용하거나 소리를 재생하지 않으며, 권한 요청 창을 띄우지 않습니다.
- 앱별 승인. 어떤 앱이 처음으로
snapzy를 사용하면 Snapzy가 허용 여부를 묻습니다.
명령 설치
바이너리는 항상 앱 내부의 다음 위치에 있습니다:
/Applications/Snapzy.app/Contents/Helpers/snapzy
에이전트와 스크립트는 이 경로를 직접 호출할 수 있습니다. 어디서든 snapzy를 입력해 사용하려면 PATH에 추가하세요:
| 방법 | 설정 방법 |
|---|---|
| Settings → Command Line(설정 → 명령줄) | 툴바의 ⓘ 버튼을 클릭한 다음 Install(설치)을 클릭합니다. 이렇게 하면 /usr/local/bin/snapzy가 생성됩니다(/usr/local/bin에 쓰기 권한이 없을 때만 관리자 암호를 묻습니다). Command line access(명령줄 접근) 스위치를 켜도 설치됩니다. Snapzy가 DMG나 임시 위치에서 실행 중이면 설치가 거부됩니다 — 먼저 응용 프로그램 폴더로 옮기세요. |
| 셸 스크립트 | install.sh는 가능하면 /usr/local/bin/snapzy 링크를 만들고, 그렇지 않으면 실행할 sudo ln -sfn … 명령을 출력합니다. 일반 파일이나 다른 도구의 링크는 절대 덮어쓰지 않습니다. |
| Homebrew | 이 명령이 포함된 첫 정식(stable) 릴리스부터 cask가 snapzy를 자동으로 링크합니다. 설정에 Copy Command(명령 복사)가 표시되면 brew reinstall --cask snapzy를 실행해 링크를 만드세요. |
| 수동 | sudo ln -sfn /Applications/Snapzy.app/Contents/Helpers/snapzy /usr/local/bin/snapzy |
명령이 앱 번들 안에 있으므로 앱 내 업데이트(Sparkle) 시 Snapzy와 함께 업데이트됩니다. 같은 팝오버의 Uninstall(제거)은 이 앱을 가리키는 링크만 제거합니다.
설정을 확인합니다:
snapzy doctor
빠른 시작
# Is Snapzy ready? (never needs approval)
snapzy status
# Find something to capture
snapzy list displays
snapzy list apps
snapzy list windows --app Safari
# Capture
snapzy capture screen -o ~/Desktop/screen.png
snapzy capture window --app Safari --max-dimension 1568 -o shot.png
snapzy capture window --active --no-shadow -o focused.png
snapzy capture area --rect 0,0,800,600 -o area.jpg --quality 0.8
명령
| 명령 | 기능 |
|---|---|
snapzy status | 앱 버전, 명령줄 접근 활성화 여부, 온보딩, 화면 기록 권한, 호출한 앱의 승인 여부를 표시합니다. 승인이 필요하지 않습니다. |
snapzy doctor | CLI 경로, PATH, 앱, 연결, 상태를 점검하고 각 실패 원인을 힌트와 함께 설명합니다. Snapzy를 실행하지 않습니다. |
snapzy version | CLI 및 앱 버전을 표시합니다. Snapzy를 실행하지 않으며, Snapzy에 연결할 수 없으면 출력 후 5로 종료합니다. |
snapzy list displays | 연결된 디스플레이(ID, 이름, 프레임, 배율, 주 디스플레이 여부). |
snapzy list windows [--app NAME] [--all] | 캡처 가능한 창을 앞쪽에서 뒤쪽 순으로 표시합니다. --all은 화면에 없는 창도 포함합니다. |
snapzy list apps | 창이 있는 실행 중인 앱. |
snapzy capture screen [--display main|all|ID] | 디스플레이 전체(기본값 main) 또는 모든 디스플레이를 캡처합니다 — 디스플레이마다 파일 하나. |
snapzy capture window --id ID | ID로 지정한 창 하나를 캡처합니다. 다른 창에 가려져 있어도 됩니다. |
snapzy capture window --app NAME [--title REGEX] [--index N] | 앱의 가장 앞쪽 창을 캡처합니다. --title은 정규식으로 필터링하고, --index는 다른 일치 항목을 선택합니다(0부터 시작, 앞쪽에서 뒤쪽 순). |
snapzy capture window --active | 가장 앞쪽 앱의 포커스된 창. |
snapzy capture area --rect x,y,w,h | 포인트 단위의 사각형. 완전히 화면 안에 있어야 합니다. |
capture window는 --id, --app, --active 중 정확히 하나를 받습니다. --no-shadow를 사용하면 창 그림자 없이 캡처합니다. 내장 도움말은 snapzy help <command>를 실행하세요.
앱 매칭
--app은 번들 ID 또는 이름을 대소문자 구분 없이 받으며, 정확한 번들 ID, 정확한 이름, 이름 접두사 순서로 찾고 — 가장 우선하는 단계만 사용합니다. 따라서 --app Code는 정확히 “Code”라는 이름의 앱과 일치하며 Codex를 섞지 않습니다. 정확히 “Code”라는 이름의 앱이 없으면 접두사 단계에서 Codex와 일치할 수 있습니다.
여러 창이 일치하면 가장 앞쪽 창이 선택되며, 결과의 matchedCandidates가 일치한 개수를 알려줍니다. 다른 창을 선택하려면 --index N을 사용하거나, list windows --app NAME으로 확인한 뒤 --id로 캡처하세요.
캡처 옵션
| 옵션 | 의미 |
|---|---|
-o, --output PATH | 캡처를 저장할 위치: 파일 경로, 디렉터리(끝에 /를 붙이거나 기존 폴더를 지정하면 Snapzy의 파일 이름 유지), 또는 이미지 바이트를 stdout으로 쓰는 -(단일 파일만). 디스플레이가 여러 개이면 파일 이름은 name-1.png, name-2.png… 형식이 됩니다. |
--format png|jpg|webp | 이미지 형식. 기본값은 --output의 확장자이며, 없으면 png입니다. 확장자와 충돌하는 형식은 오류입니다. |
--quality 0…1 | JPEG 품질(jpg 전용), 기본값 0.9. |
--max-dimension PX | 가장 긴 변이 최대 PX 픽셀이 되도록 축소합니다(확대하지 않음). 비전 모델에는 1568이 적합합니다. |
--cursor | 마우스 포인터를 포함합니다. |
--force | --output 위치의 기존 파일을 덮어씁니다. 이 옵션이 없으면 기존 파일이 있을 때 캡처 전에 실패합니다. |
-o가 없으면 파일은 Snapzy의 임시 보관 폴더(~/Library/Application Support/Snapzy/CLI/Captures/)에 남고 24시간 후 삭제됩니다 — 파일을 보관하려면 항상 -o를 전달하세요.
전역 옵션
모든 명령에서 사용할 수 있습니다:
| 옵션 | 기본값 | 의미 |
|---|---|---|
--json | 끔 | stdout이 터미널이어도 JSON을 출력합니다(보기 좋게 정렬). |
--timeout S | 30 | 각 요청을 기다리는 시간(초). |
--launch-timeout S | 15 | Snapzy가 시작될 때까지 기다리는 시간(초). |
--no-launch | 끔 | Snapzy가 실행 중이 아닐 때 실행하는 대신 실패합니다. |
출력
stdout이 터미널이 아닐 때(파이프, 에이전트, 스크립트) 또는 --json을 사용하면 출력은 JSON입니다. 터미널에서는 항목마다 읽기 쉬운 한 줄이 출력됩니다. 오류는 같은 모드로 stderr에 출력됩니다.
{"durationMs":244,"files":[{"bytes":1204134,"displayID":1,"format":"png","height":2338,"path":"/Users/me/shot.png","scale":2,"width":3600}]}
scale은 저장된 파일의 포인트당 픽셀 수입니다(--max-dimension사용 시 디스플레이 배율보다 낮아짐).format은png,jpeg,webp중 하나입니다.- 창 캡처에는
window(id,title,app {name, bundleID, pid},frame,displayID,isOnScreen,isActive)와matchedCandidates도 포함됩니다. -o -를 사용하면 stdout으로 이미지 바이트가 전달되며, JSON 메타데이터는--json도 함께 전달할 때만 stderr로 출력됩니다.
오류는 다음과 같은 형태입니다:
{"error":{"code":"targetNotFound","message":"…","hint":"…"}}
좌표
모든 프레임과 --rect 값은 주 디스플레이의 왼쪽 상단을 원점으로 하는 전역 포인트를 사용합니다. 주 디스플레이의 왼쪽이나 위쪽에 있는 디스플레이는 음수 좌표를 가지며 — --rect -1440,0,800,600은 그대로 동작합니다. list windows에서 얻은 창 frame은 capture area에 바로 전달할 수 있습니다.
종료 코드
| 종료 코드 | 오류 코드 | 의미 |
|---|---|---|
0 | — | 성공 |
1 | internal | 예기치 않은 실패 |
2 | invalidArguments | 잘못된 플래그, 일부가 화면 밖에 있는 영역, 또는 --force 없이 지정한 기존 --output |
3 | permissionDenied, onboardingIncomplete | 화면 기록 권한이 없거나 아직 활성화되지 않음, 또는 Snapzy 설정이 완료되지 않음 |
4 | targetNotFound | 해당 디스플레이, 창 또는 앱이 없거나, 영역이 화면 밖에 있음 |
5 | appUnavailable, launchTimeout, disabled, busy, versionMismatch, unknownMethod | Snapzy에 연결할 수 없음, 명령줄 접근이 꺼져 있음, 다른 캡처가 실행 중임, 화면이 잠겨 있음, 또는 버전이 일치하지 않음 |
7 | notAuthorized | 호출한 앱이 거부되었거나, 제때 승인되지 않았거나, 식별할 수 없음 |
승인 및 허용된 앱
status를 제외한 모든 명령은 호출한 앱의 승인이 필요합니다 — 터미널, iTerm, VS Code, Cursor, Claude처럼 snapzy를 실행하는 앱을 말합니다. Snapzy는 snapzy 프로세스에서 위로 거슬러 올라가 처음 나오는 일반 앱을 찾아 식별하고, 해당 앱의 코드 서명을 확인합니다. 검증할 수 없는 앱은 일반 아이콘, 경고, 그리고 디스크상의 실제 위치와 함께 표시됩니다.
첫 요청 시 Always Allow(항상 허용), Allow Once(한 번 허용), Don't Allow(허용 안 함) 버튼이 있는 확인 창이 표시됩니다:
- Return 키는 버튼을 선택하지 않으며, Escape 키는 Don't Allow를 의미합니다.
- 확인 창은 25초 후 시간 초과되며 명령은
7로 종료됩니다. - Allow Once는 해당
snapzy명령의 나머지 부분에만 적용됩니다. - 결정은 이 Mac에만 저장되며
config.toml로 내보내지지 않습니다.
Settings → Command Line → Allowed apps(설정 → 명령줄 → 허용된 앱)에서 결정을 검토하거나 철회할 수 있습니다(Remove(제거) 또는 Remove All(모두 제거)). snapzy://settings/command-line으로 바로 열 수 있습니다.
명령줄 캡처가 실행되는 동안 메뉴 막대 아이콘에 색이 입혀집니다. 메뉴 막대 아이콘이 숨겨져 있으면 대신 알림으로 해당 앱의 이름을 알려줍니다.
끄기
Settings → Command Line(설정 → 명령줄)의 Command line access(명령줄 접근) 스위치는 기본적으로 켜져 있습니다. 꺼져 있으면 Snapzy가 소켓을 닫고 모든 명령이 disabled(종료 코드 5)로 실패합니다. 같은 설정을 config.toml에서도 사용할 수 있습니다:
[general]
cli_enabled = true
AI 에이전트에서 snapzy 사용하기
snapzy status를 한 번 실행합니다.authorization이undetermined이면 다음 캡처 시 Snapzy 확인 창이 나타납니다 — 25초 안에 Always Allow 또는 Allow Once를 클릭하세요.list displays,list apps,list windows로 캡처 대상을 찾습니다.- 항상
-o로 직접 지정한 경로에 캡처합니다. - 비전 입력에 적합한 크기로 이미지를 유지하도록
--max-dimension 1568을 추가한 뒤, 반환된files[].path를 읽습니다.
Snapzy 저장소에는 에이전트에게 이 워크플로우를 알려주는 기성 에이전트 스킬이 skills/snapzy에 포함되어 있습니다.
문제 해결
먼저 snapzy doctor를 실행하세요 — 각 실패 원인을 설명하고 해결 방법을 제안합니다.
| 증상 | 원인 및 해결 방법 |
|---|---|
disabled (5) | 명령줄 접근이 꺼져 있습니다. Settings → Command Line(설정 → 명령줄)에서 켜세요. |
launchTimeout (5) | Snapzy가 시작되었지만 --launch-timeout 안에 응답하지 않았습니다 — 대부분 명령줄 접근이 꺼져 있거나 앱 시작이 느리기 때문입니다. |
permissionDenied (3), “granted but not usable yet” | Snapzy가 실행 중일 때 화면 기록 권한이 부여되었습니다. Snapzy를 다시 실행하세요. 문제가 계속되면 System Settings → Privacy & Security → Screen & System Audio Recording(시스템 설정 → 개인정보 보호 및 보안 → 화면 및 시스템 오디오 녹음)에서 Snapzy를 제거한 뒤 다시 추가하세요. |
onboardingIncomplete (3) | Snapzy를 열고 설정을 완료하세요. |
appUnavailable (5), “The screen is locked or asleep” | macOS는 세션이 잠겨 있는 동안 캡처를 허용하지 않습니다. |
notAuthorized (7) | 호출한 앱이 거부되었거나 아무도 확인 창에 응답하지 않았습니다. Settings → Command Line → Allowed apps(설정 → 명령줄 → 허용된 앱)를 확인하세요. |
snapzy: command not found | 명령이 PATH에 없습니다. Settings → Command Line → Install(설정 → 명령줄 → 설치)을 사용하거나, Homebrew로 설치한 경우 brew reinstall --cask snapzy를 실행하거나, Snapzy.app 내부의 전체 경로를 호출하세요. |