CLI 命令行

Snipkap 动作 Schema 6 的命令行参考。Windows 与 macOS 命令、校验和结果码一致。

CLI、URL Scheme、单实例 IPC 和应用菜单共用动作 Schema 6。适合脚本、AI Agent，以及需要结果文件的自动化。需要可读结果时始终加 --to。

# Windows
Snipkap.exe <command>

# macOS 安装版
/Applications/Snipkap.app/Contents/MacOS/Snipkap <command>

后续 CLI 请求会转交给已经运行的主实例。交互或异步动作返回“已接受”；查询结果和 OCR 文件以新文件发布，不覆盖已有文件。

查阅命令文档

Snipkap --help
Snipkap --help-json

选项	输出	说明
`--help`	UTF-8 纯文本	打印命令文档后立即退出，不启动托盘或图形界面
`--help-json`	UTF-8 JSON	包含帮助 Schema、动作 Schema、命令、结果码和注意事项
`help`	图形窗口	打开应用内帮助，不写标准输出

--help 与 --help-json 必须单独使用，选项名区分大小写。成功时结果码均为 0。

通用规则

命令名和值不区分英文大小写；选项名必须按下文拼写。
布尔值接受 on / off、true / false、1 / 0、enable / disable、enabled / disabled。
<id> 是 32 位小写十六进制。<id|all> 也可操作全部贴图；copy / save 不接受 all。
<path> 必须是本机绝对路径；含空格时按终端规则加引号。--to 目标必须尚不存在。
单个参数最多 32767 字符；pin-paths 最多 256 个路径，合计不超过 1 MiB。
别名：pin = pin-clipboard；rectangle = rect；shape = fixed；watermark = personalization。

异步语义

截图和 OCR 的结果码 0 只表示请求已接受。脚本应等待 --to 指定的文件出现再解析，不要用固定睡眠假设完成时间。

capture

Snipkap capture [--mode rect|irregular|long|gif|fixed|delay|whiteboard]
                [--irregular pen|freehand] [--horizontal]
                [--sides 3..64] [--width 1..32768 --height 1..32768]
                [--output interactive|clipboard|save|pin|history]
                [--to <path>]

启动一次截图。默认 --mode rect、--output interactive。

选项	类型	必填	说明
`--mode`	枚举	否	`rect` 矩形；`irregular` 异型；`long` 长截图；`gif` 动图；`fixed` 固定形状；`delay` 延时；`whiteboard` 白板
`--irregular`	枚举	仅异型	`pen` 钢笔路径；`freehand` 自由路径
`--horizontal`	开关	否	仅用于横向长截图；不写则为纵向
`--sides`	`3..64`	仅固定形状	正多边形边数
`--width` / `--height`	`1..32768`	仅固定形状	必须成对出现
`--output`	枚举	否	`interactive` 进入编辑器；`clipboard` 复制；`save` 保存；`pin` 贴图；`history` 写入本地历史
`--to`	路径	保存时	隐式选择 `save`；若同时写 `--output`，只能是 `save`

gif、delay、whiteboard 只接受 interactive，完成后由用户选择最终输出。长截图和 history 输出要求对应功能当前可用，且本地历史已启用。

Snipkap capture --mode rect --output clipboard
Snipkap capture --mode irregular --irregular pen --output clipboard
Snipkap capture --mode long --horizontal --output pin
Snipkap capture --mode fixed --sides 6 --width 800 --height 600 --to /absolute/path/capture.png

免费版水印

免费版所有截图输出都强制合成内置官方水印，包括 CLI、剪贴板、文件、Pin 和历史。Pro 按用户保存的水印设置输出。

创建贴图

Snipkap pin-clipboard
Snipkap pin-paths <path> [<path> ...]
Snipkap restore-pins

命令	说明
`pin-clipboard`	从当前剪贴板创建贴图。别名 `pin`
`pin-paths`	为每个本地路径创建贴图
`restore-pins`	恢复上次保存的穿透贴图会话

pins

Snipkap pins list [--to <json-path>]
Snipkap pins close <id|all>
Snipkap pins passthrough <id|all> on|off
Snipkap pins rotate <id|all> left|right|180
Snipkap pins mirror <id|all>
Snipkap pins opacity <id|all> <10..100>
Snipkap pins scale <id|all> <10..1000>
Snipkap pins reset <id|all>
Snipkap pins copy <id>
Snipkap pins save <id> --to <image-path>

子命令	说明
`list`	列出当前贴图；`--to` 写机器可读 JSON
`close`	关闭一张或全部贴图
`passthrough`	开关鼠标穿透
`rotate`	`left` / `right` / `180`
`mirror`	水平镜像
`opacity`	透明度百分比 `10..100`
`scale`	相对原始大小的百分比 `10..1000`
`reset`	恢复变换和透明度
`copy`	复制到剪贴板，不接受 `all`
`save`	保存到新文件，不接受 `all`

history

Snipkap history enable|disable
Snipkap history pause|resume
Snipkap history settings --days <1..365> --max-entries <1..10000>
Snipkap history open
Snipkap history list [--to <json-path>]
Snipkap history latest
Snipkap history pin|copy|delete <id>
Snipkap history save <id> --to <image-path>
Snipkap history clear
Snipkap history dock show|hide|toggle

delete 与 clear 始终要求用户确认。

ocr

Snipkap ocr history <id> [--output panel|clipboard|text|json] [--to <path>]
Snipkap ocr path <image-path> [--output panel|clipboard|text|json] [--to <path>]

默认 --output panel。text / json 必须提供 --to；panel / clipboard 不接受 --to。

成功 JSON 包含 source、完整 text 和文字区域 regions。每个区域同时给出阅读顺序用的 line 与同一行前置空白 separator。异步识别失败时 JSON 含空的 text、regions 和 error。

Snipkap ocr path /absolute/path/image.png --output json --to /absolute/path/ocr.json

capabilities / status

Snipkap capabilities [--to <json-path>]
Snipkap status [--to <json-path>]

命令	JSON 内容
`capabilities`	应用版本、动作 Schema、平台、`edition`、`watermark` 和可用能力
`status`	另含权限、历史配置、Pin 数量、历史 Dock 与截图会话状态

未指定 --to 时只显示简短桌面反馈。AI 应始终指定 JSON 目标。免费版返回 edition=free、watermark.required=true；Pro 返回 edition=pro、watermark.management=true。

设置与生命周期

Snipkap smart-paste on|off
Snipkap launch-at-login on|off
Snipkap settings open <section>
Snipkap preferences
Snipkap entitlement
Snipkap tool scale-ruler|caliper|angle
Snipkap help
Snipkap about
Snipkap quit

settings open 的 <section>：general、ocr、capture-hotkey、pin-hotkey、permissions、history、personalization、watermark、translation、about。

命令	行为
`settings open permissions`	Windows 打开通用页并说明本平台无需额外授权；macOS 打开应用内权限说明
`settings open watermark`	个性化设置中的水印页别名
`preferences`	兼容入口。Windows 打开通用设置；macOS 打开截图快捷键设置
`entitlement`	显示当前免费版 / Pro。机器可读结果请用 `capabilities --to` 或 `status --to`
`tool`	切换桌面比例尺、卡尺或角度测量

结果码

码	含义
`0`	成功或已接受
`1`	执行失败
`2`	参数无效
`3`	当前忙
`4`	文件、历史或 Pin 不存在
`5`	权限不足或用户拒绝
`6`	当前平台不支持
`7`	超过资源限制

浏览器或快捷指令触发请改用 URL Scheme。URL 不能把结果码同步返回调用页。

本页目录