GetWebP CLI – LLM 上下文文档

GetWebP CLI -- LLM 上下文文档

本文档针对需要理解和调用 GetWebP CLI 的 AI 代理（Cursor、Claude、Copilot 等）进行了优化。版本：1.2.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 个并发）和 watch 命令。许可证在 getwebp.com/pricing 购买。

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

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

所有命令支持 --json（别名 -j）以在 stdout 上获得结构化 NDJSON（换行分隔 JSON）事件。人类可读的消息和警告转到 stderr。每个 stdout 行是一个 JSON 对象。

默认情况下，convert 使用 SSIM 自动质量找到与源文件视觉上完全相同的最小 WebP。使用 --quality <N> 指定固定质量，或使用 --no-auto-quality 使用固定质量 80。

命令快速参考#

convert#

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

注意： -q 是全局 --quiet 的别名，不是 --quality 的别名。

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

watch（仅限 Pro，v1.2.0+）#

getwebp watch [...paths] [options]

作为前台守护程序运行。按 Ctrl+C 可优雅关闭。

auth#

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

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

status#

getwebp status [--json]

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

logout#

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

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

全局标志#

重大变更 (v1.2.0)： -v 此前是 --version 的别名，现在是 --verbose。请使用 -V 获取版本。

退出代码#

NDJSON 输出#

每次 --json 调用都在 stdout 上发出 NDJSON。每行是一个 JSON 事件。

信封（必需字段，所有事件）#

{
  "@timestamp": "2026-04-11T10:00:00.123Z",
  "@level": "info | warn | error",
  "@message": "人类可读摘要",
  "@module": "getwebp.<command>",
  "type": "<event-type>",
  "data": {}
}

第一行——版本前言（始终）#

{"@timestamp":"2026-04-11T10:00:00.100Z","@level":"info","@message":"GetWebP CLI 1.2.1","@module":"getwebp.cli","type":"version","data":{"getwebp":"1.2.1","ui":"1"}}

convert 事件#

convert.completed 数据#

{
  "processed": 3,
  "total": 3,
  "successCount": 3,
  "failedCount": 0,
  "results": [
    {
      "file": "photo.jpg",
      "status": "success",
      "originalSize": 204800,
      "newSize": 133120,
      "savedRatio": 0.35,
      "saved": "35.0%",
      "quality": 78,
      "qualityMode": "auto"
    }
  ]
}

convert.truncated 数据#

{
  "processed": 20,
  "skipped": 5,
  "limit": 20,
  "upgrade_url": "https://getwebp.com/pricing"
}

watch 事件#

watch 事件使用带有 event 和 ts 字段的扁平格式（非标准 NDJSON 信封），watch.failed 错误事件除外（使用标准信封）。

auth 事件#

status 事件#

status.reported 数据#

{
  "version": "1.2.1",
  "plan": "free | pro",
  "licenseKeySuffix": "A1B2",
  "expiresAt": "2027-04-01T00:00:00.000Z",
  "devicesUsed": 1,
  "devicesLimit": 5,
  "cached": true
}

logout 事件#

JSON 错误代码（data.code）#

常见用法场景#

将目录中的所有图像转换为 WebP#

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

使用 NDJSON 输出递归转换#

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

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

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

预览而不写入磁盘#

getwebp convert ./images --dry-run

CI/CD：转换并解析结果#

getwebp convert ./src/images -o ./dist/images --quality 85 --json > out.ndjson
grep '"type":"convert.completed"' out.ndjson | jq '.data.failedCount == 0'

监视目录（Pro）#

getwebp watch ./src/images -o ./dist/images

以编程方式检查计划#

getwebp status --json | grep '"type":"status.reported"' | jq -r '.data.plan'

在 CI 中激活许可证#

getwebp auth "$GETWEBP_LICENSE_KEY" --json | grep '"type":"auth.completed"'

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

getwebp logout --force --json

层级对比#

已知限制#

1. 输出格式仅为 WebP。 没有转换为其他格式的选项。
2. 免费层级：每次运行 20 文件限制。 超过限制的文件被跳过，不排队。退出代码 6。
3. 免费层级：每个文件 3 秒人为延迟。 没有许可证无法绕过。
4. 免费层级：--concurrency 被忽略。 处理始终是串行的。
5. 注销需要网络。 使用网络仪表板作为回退。
6. --json 输出是 NDJSON（流式）。 每行一个 JSON 对象。逐行解析。
7. 质量限制在 1-100。 无效值静默回退到 80。
8. 默认质量是自动（SSIM）。 --quality 标志用固定值覆盖它。
9. 支持 WebP 到 WebP 重新编码，但可能增加文件大小。检查 savedRatio 中的负值。
10. macOS Gatekeeper 可能阻止未签名的二进制文件。 运行 xattr -cr getwebp 以移除隔离属性。
11. 输入/输出没有用于图像数据的管道。 输入必须是文件路径；输出始终写入磁盘。

常数（来自源）#