命令行 (snapzy)

概述

Snapzy 附带一个 snapzy 命令，让 AI 代理（Claude Code、Cursor、Codex 等）、Shell 脚本以及你自己的终端无需操作鼠标即可截图。每条命令都会返回文件路径、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 或临时位置运行时会拒绝安装——请先将其移到“应用程序”文件夹。
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	参数错误、区域部分超出屏幕，或在未使用 --force 时 --output 已存在
3	permissionDenied, onboardingIncomplete	缺少屏幕录制权限或权限尚未生效，或 Snapzy 设置尚未完成
4	targetNotFound	不存在该显示器、窗口或应用，或区域位于屏幕之外
5	appUnavailable, launchTimeout, disabled, busy, versionMismatch, unknownMethod	无法连接 Snapzy、命令行访问已关闭、另一个捕获正在进行、屏幕已锁定，或版本不匹配
7	notAuthorized	调用方应用被拒绝、未及时获得授权，或无法识别

授权与允许的应用

除 status 外，所有命令都需要调用方应用获得授权——即你运行 snapzy 的应用，例如终端、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 会关闭其套接字，所有命令都会以 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；如果问题仍然存在，请在 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 内的完整路径。