命令列 (snapzy)

總覽

Snapzy 隨附一個 snapzy 指令，讓 AI 代理（Claude Code、Cursor、Codex…）、shell 指令碼以及您自己的終端機無需動到滑鼠即可擷取螢幕截圖。每個指令都會傳回檔案路徑、JSON 中繼資料，以及有意義的結束代碼。

• 精簡用戶端。 snapzy 透過私有的 Unix socket 與執行中的 Snapzy 應用程式溝通。擷取由 Snapzy 執行，因此螢幕錄製權限保留在 Snapzy 上 — 您的終端機或代理永遠不需要此權限。
• 自動為您啟動 Snapzy。 如果 Snapzy 尚未執行，指令會在背景開啟它並等待其就緒（完成歡迎引導後不會顯示啟動畫面）。傳入 --no-launch 可改為直接失敗。
• 無介面 (Headless)。 命令列擷取永遠不會開啟快速存取、不會動到剪貼簿、不會新增歷史紀錄項目、不會套用預設組合或播放音效，也不會觸發權限提示。
• 逐一應用程式核准。 某個應用程式第一次使用 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 或暫存位置執行時，安裝會被拒絕 — 請先將其移至「應用程式」檔案夾。
Shell 指令碼	install.sh 會在可行時連結 /usr/local/bin/snapzy，否則會印出需執行的 sudo ln -sfn … 指令。它永遠不會覆寫一般檔案或其他工具的連結。
Homebrew	從第一個包含此指令的穩定版本開始，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	旗標錯誤、區域部分超出螢幕，或 --output 已存在但未指定 --force
3	permissionDenied, onboardingIncomplete	缺少螢幕錄製權限或尚未生效，或 Snapzy 設定尚未完成
4	targetNotFound	找不到該顯示器、視窗或應用程式，或區域位於螢幕外
5	appUnavailable, launchTimeout, disabled, busy, versionMismatch, unknownMethod	無法連線至 Snapzy、命令列存取已關閉、另一個擷取正在執行、螢幕已鎖定，或版本不相符
7	notAuthorized	呼叫端應用程式遭拒、未及時獲得核准，或無法識別

核准與允許的應用程式

除了 status 之外，所有指令都需要呼叫端應用程式獲得核准 — 也就是您用來執行 snapzy 的應用程式，例如 Terminal、iTerm、VS Code、Cursor 或 Claude。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 會關閉其 socket，所有指令都會以 disabled（結束代碼 5）失敗。相同的設定也可在 config.toml 中使用：

[general]
cli_enabled = true

搭配 AI 代理使用 snapzy

1. 先執行一次 snapzy status。如果 authorization 為 undetermined，下一次擷取時將會出現 Snapzy 提示 — 請在 25 秒內點按 Always Allow（永遠允許）或 Allow Once（允許一次）。
2. 使用 list displays、list apps 或 list windows 找出擷取目標。
3. 一律使用 -o 擷取到您選擇的路徑。
4. 加上 --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；若問題持續，請在系統設定 → 隱私權與安全性 → 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 內的完整路徑。