本文档针对需要理解和调用 GetWebP CLI 的 AI 代理（Cursor、Claude、Copilot 等）进行了优化。

GetWebP CLI -- LLM 上下文文档

本文档针对需要理解和调用 GetWebP CLI 的 AI 代理（Cursor、Claude、Copilot 等）进行了优化。版本：1.0.1。

产品描述 #

GetWebP CLI 是一个跨平台命令行工具，将图像（JPG、PNG、BMP、WebP）批量转换为优化的 WebP 格式。它作为 macOS (ARM64, x64)、Linux (x64) 和 Windows (x64) 的独立二进制文件分发。二进制文件名为 getwebp。

CLI 有两个许可证层级：Free 和 Pro。Free 层级无需激活即可使用，但限制转换为每次运行 20 个文件，文件之间 3 秒延迟，仅限串行处理。Pro 层级需要通过 getwebp auth <key> 激活许可证，解锁无限制文件、即时处理和并行工作者（最多 32 个并发）。许可证在 getwebp.com/pricing 购买。

CLI 使用基于 JWT 的离线优先许可。一旦激活，许可证在本地缓存并在没有持久网络连接的情况下工作。status 命令在离线时报告缓存的数据。

原始文件永远不会被修改或删除。输出 WebP 文件默认写入源文件旁边，或写入指定的输出目录。

所有命令支持 --json 以在 stdout 上获得结构化的机器可读输出。人类可读的消息和警告转到 stderr。JSON 输出是由 \n 终止的单行。

命令快速参考 #

convert #

getwebp convert [path] [options]
getwebp convert -i <path> [options]

标志	别名	类型	默认值	层级	描述
`<path>` (位置)	--	string	--	All	输入文件或目录
`--input`	`-i`	string	--	All	输入文件或目录（位置的替代）
`--output`	`-o`	string	与源相同	All	输出目录
`--quality`	`-q`	number (1-100)	80	All	WebP 质量。无效值回退到 80。
`--recursive`	`-r`	boolean	false	All	处理子目录
`--concurrency`	--	number (1-32)	CPU 核心 - 1	Pro	并行工作者。在 Free 层级上被忽略。
`--dry-run`	--	boolean	false	All	预览文件而不写入
`--skip-existing`	--	boolean	false	All	如果 .webp 已在输出路径存在则跳过
`--json`	--	boolean	false	All	在 stdout 上输出结构化 JSON

支持的输入格式：.jpg、.jpeg、.png、.bmp、.webp 输出格式：.webp（始终）

auth #

getwebp auth <license-key> [--json]

激活许可证密钥并将其绑定到当前设备。

status #

getwebp status [--json]

显示版本、计划层级、许可证后缀、过期日期和设备使用情况。

logout #

getwebp logout [--force] [--json]

从设备解绑许可证。需要网络。--force 或 --json 跳过交互式确认。

全局标志 #

标志	别名	描述
`--version`	`-v`	打印版本 (`getwebp/1.0.1`)
`--help`	--	显示帮助
`--json`	--	JSON 输出（所有命令）
`--verbose`	--	详细输出
`--debug`	--	调试输出（隐含 --verbose）

退出代码 #

代码	常数	含义	可重试
0	Success	所有文件处理成功	--
1	GenericError	未分类的错误	因情况而异
2	PartialFailure	某些文件失败，其他成功	否（修复失败的文件）
3	AuthError	许可证无效、过期或设备不匹配	否
4	NetworkError	API 请求失败或超时	是

JSON 输出架构 #

信封（所有命令）#

{
  "success": boolean,
  "status"?: "success" | "error" | "partial",
  "error"?: string,         // 机器可读的错误代码（失败时）
  "message"?: string,       // 人类可读（失败或部分时）
  "data"?: object,          // 命令特定的负载
  "upgrade"?: { "url": string, "activateCommand": string }
}

convert -- 成功 #

{
  "success": true,
  "status": "success",
  "total": number,
  "successCount": number,
  "failedCount": number,
  "results": [
    {
      "file": string,
      "status": "success",
      "originalSize": number,    // 字节
      "newSize": number,         // 字节
      "savedRatio": number,      // 0 到 1，如果 WebP 更大则为负
      "saved": string            // 例如 "35.0%"
    }
  ]
}

convert -- 部分失败 #

与成功形状相同，但 "success": false、"status": "error"，失败项有：

{ "file": string, "status": "error", "error": string }

convert -- 免费计划限制已达 #

{
  "success": true,
  "status": "partial",
  "message": string,
  "data": { "processed": number, "skipped": number },
  "upgrade": { "url": string, "activateCommand": string }
}

convert -- 跳过项 (--skip-existing)#

{ "file": string, "status": "skipped", "reason": "existing" }

auth -- 成功/错误 #

{ "success": true, "data": { "message": string } }
{ "success": false, "status": "error", "error": string, "message": string }

status -- 活跃许可证 #

{
  "success": true,
  "data": {
    "version": string,
    "mode": "free" | "pro",
    "licenseKeySuffix"?: string,
    "expiresAt"?: string,          // ISO 8601
    "devicesUsed"?: number,
    "devicesLimit"?: number,
    "cached"?: true                // 仅在离线时出现
  }
}

logout -- 成功/错误 #

{ "success": true, "data": { "message": string } }
{ "success": false, "status": "error", "error": string, "message": string }

JSON 错误代码 #

代码	命令	含义	可重试
`missing_input`	convert	未指定输入路径	否
`unknown_error`	auth	未分类的激活失败	因情况而异
`network_unreachable`	logout	无法访问 API 服务器	是
`not_activated`	logout	设备上无活跃许可证	否
`device_not_found`	logout	设备已解绑	否
`invalid_token`	logout	令牌已过期或已撤销	否

常见用法场景 #

将目录中的所有 PNG 文件转换为 WebP #

getwebp convert ./assets -o ./assets-webp

在项目的图像文件夹中递归转换所有图像 #

getwebp convert ./src/images -r -o ./dist/images

高质量转换，跳过已转换的文件 #

getwebp convert ./images -q 95 --skip-existing

预览将被转换的内容（无磁盘写入）#

getwebp convert ./images --dry-run

CI/CD 管道：转换并在错误时失败 #

result=$(getwebp convert ./src/images -o ./dist/images -q 85 --json 2>/dev/null)
echo "$result" | jq -e '.success'

以编程方式检查当前许可证状态 #

getwebp status --json | jq -r '.data.mode'

在 CI 中激活许可证 #

getwebp auth "$GETWEBP_LICENSE_KEY" --json | jq -e '.success'

从设备停用许可证（非交互式）#

getwebp logout --force --json

使用 8 个工作者的并行转换 (Pro)#

getwebp convert ./images --concurrency 8

从转换运行获得节省的总字节数 #

getwebp convert ./images --json 2>/dev/null | jq '[.results[] | select(.status == "success") | (.originalSize - .newSize)] | add'

层级对比 #

限制	Free	Pro
每次运行的文件数	20	无限制
每个文件的延迟	3 秒	无
并行工作者	1（串行）	自动（CPU 核心 - 1）
最大 --concurrency	被忽略	32

已知限制 #

输出格式仅为 WebP。 没有转换为其他格式的选项。
免费层级：每次运行 20 文件限制。 超过限制的文件被跳过，不排队。
免费层级：每个文件 3 秒人为延迟。 没有许可证无法绕过。
免费层级：--concurrency 被忽略。 处理始终是串行的。
注销需要网络。 设备无法离线解绑。使用网络仪表板作为回退。
无流式 JSON。 convert 命令在所有文件处理后发出单个 JSON 对象，而不是每文件事件。
质量限制在 1-100。 无效值静默回退到 80。
支持 WebP 到 WebP 重新编码，但可能增加文件大小。检查 savedRatio 中的负值。
macOS Gatekeeper 可能阻止未签名的二进制文件。 运行 xattr -cr getwebp 以移除隔离属性。
输入/输出没有用于图像数据的管道。 输入必须是文件路径；输出始终写入磁盘。

stderr 警告 #

CLI 可能向 stderr 发出警告，无论 --json 如何。这些不是 JSON 流的一部分。使用 2>/dev/null 压制。示例：

warn: Free plan: max 20 files, 3s delay between each.
warn: No --output specified: converted files will be written next to source files.
warn: Conflict: a.png, a.jpg all map to a.webp -- only the last processed will survive

常数（来自源）#

常数	值
免费层级文件限制	20
免费层级延迟	3000 ms
默认质量	80
默认并发性	CPU 核心 - 1（最小 1）
网络心跳超时	3000 ms
API 超时	5000 ms

文档

GetWebP CLI – LLM 上下文文档