GetWebP CLI 命令参考

所有 GetWebP CLI 命令、标志和输出格式的完整参考。

快速参考 #

命令	描述
`getwebp convert [path]`	将图像转换为 WebP 格式
`getwebp auth <license-key>`	激活许可证密钥
`getwebp status`	显示许可证和版本信息
`getwebp logout`	从此设备解绑许可证

全局标志 #

这些标志适用于所有命令。

标志	别名	描述	默认值
`--version`	`-v`	打印 CLI 版本并退出	--
`--help`	--	显示帮助文本并退出	--
`--json`	--	在 stdout 上输出结构化 JSON（人类消息转到 stderr）	关闭
`--verbose`	--	启用详细输出	关闭
`--debug`	--	启用调试输出（隐含 `--verbose`）	关闭

# 打印版本
getwebp --version
# 输出：getwebp/1.0.1
 
# 显示帮助
getwebp --help

`getwebp convert`#

将一个或多个图像转换为 WebP 格式。原始文件永远不会被修改或删除。

概要 #

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

位置 [path] 参数和 -i, --input 标志可互换。如果两者都提供，位置参数优先。

标志 #

标志	别名	描述	默认值	层级
`<path>` (位置)	--	要转换的输入文件或目录	--	所有
`--input <path>`	`-i`	输入文件或目录（位置参数的替代）	--	所有
`--output <path>`	`-o`	已转换文件的输出目录	与源相同的目录	所有
`--quality <number>`	`-q`	WebP 质量，1-100	`80`	所有
`--recursive`	`-r`	递归处理子目录中的图像	关闭	所有
`--concurrency <number>`	--	并行工作者数，最多 32	CPU 核心数 - 1	Pro
`--dry-run`	--	预览将被转换的文件（不写入）	关闭	所有
`--skip-existing`	--	如果输出路径已存在 `.webp` 文件则跳过	关闭	所有
`--json`	--	CI 管道和 AI 代理的 JSON 输出	关闭	所有

注意：

在免费计划上，--concurrency 被忽略。处理是串行的，文件之间有 3 秒延迟，每次运行限制 20 个文件。
质量限制在 1-100 范围内。无效值回退到 80。
当 --output 被省略时，.webp 文件被写入源文件旁边。

支持的输入格式 #

输入	输出
JPG / JPEG	WebP
PNG	WebP
BMP	WebP
WebP	WebP (重新编码)

示例 #

转换单个图像：

getwebp convert photo.png

✓ photo.png
Done: 1 succeeded, 0 failed
Avg saved: 34.2%

使用自定义输出转换目录：

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

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

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

递归扫描子目录：

getwebp convert ./images -r

使用 8 个工作者的并行处理 (Pro)：

getwebp convert ./images --concurrency 8

预览将被转换的内容（不写入）：

getwebp convert ./images --dry-run

CI/CD 管道的 JSON 输出：

getwebp convert ./images --json

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

使用 -i 标志而不是位置参数：

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

免费计划行为 #

当未激活许可证时：

每次运行最多20 个文件。剩余文件报告为已跳过。
3 秒延迟在每个文件之间。
--concurrency 被忽略（仅串行处理）。

当到达文件限制时，免费计划上的 JSON 输出：

{
  "success": true,
  "status": "partial",
  "message": "Processed 20 images. Free plan limit reached (5 remaining). Upgrade at getwebp.com/pricing, then run: getwebp auth <your-key>",
  "data": {
    "processed": 20,
    "skipped": 5
  },
  "upgrade": {
    "url": "https://getwebp.com/pricing",
    "activateCommand": "getwebp auth <your-key>"
  }
}

`getwebp auth`#

激活许可证密钥以解锁 Pro 功能。将许可证绑定到当前设备。

概要 #

getwebp auth <license-key>

标志 #

标志	别名	描述	默认值	层级
`<license-key>` (必需)	--	要激活的许可证密钥	--	--
`--json`	--	JSON 输出	关闭	所有

示例 #

激活许可证：

getwebp auth XXXX-XXXX-XXXX-XXXX

Verifying license...
✓ Activated! Pro plan unlocked.

使用 JSON 输出激活：

getwebp auth XXXX-XXXX-XXXX-XXXX --json

{
  "success": true,
  "data": {
    "message": "Activated — Pro plan unlocked"
  }
}

失败的激活 (JSON)：

{
  "success": false,
  "status": "error",
  "error": "unknown_error",
  "message": "Invalid license key"
}

在 getwebp.com/pricing 购买许可证。

`getwebp status`#

显示当前许可证信息、计划层级、过期日期和设备使用情况。

概要 #

getwebp status

标志 #

标志	别名	描述	默认值	层级
`--json`	--	JSON 输出	关闭	所有

示例 #

免费计划（未激活许可证）：

getwebp status

Version    : 1.0.1
Mode       : Free

Pro 计划：

getwebp status

Version    : 1.0.1
Mode       : Pro
License    : xxxx-xxxx-xxxx-A1B2
Expires    : 2027-04-01
Devices    : 1 / 3 used

JSON 输出：

getwebp status --json

{
  "success": true,
  "data": {
    "version": "1.0.1",
    "mode": "pro",
    "licenseKeySuffix": "A1B2",
    "expiresAt": "2027-04-01T00:00:00.000Z",
    "devicesUsed": 1,
    "devicesLimit": 3
  }
}

免费计划 (JSON)：

{
  "success": true,
  "data": {
    "version": "1.0.1",
    "mode": "free"
  }
}

缓存状态（离线，网络无法连接）：

当 API 无法访问但缓存的 JWT 存在时，从本地缓存返回状态：

{
  "success": true,
  "data": {
    "version": "1.0.1",
    "mode": "pro",
    "cached": true,
    "expiresAt": "2027-04-01T00:00:00.000Z"
  }
}

`getwebp logout`#

从此设备解绑许可证，释放设备插槽。需要网络访问。

概要 #

getwebp logout [options]

标志 #

标志	别名	描述	默认值	层级
`--force`	`-f`	跳过交互式确认提示	关闭	所有
`--json`	--	JSON 输出	关闭	所有

注意： 在脚本和 CI 环境中，使用 --force 跳过交互式确认提示。使用 --json 时，确认提示也会自动跳过。

示例 #

交互式注销：

getwebp logout

? Confirm unbind license from this device? This cannot be undone. (y/N) y
✓ Successfully unbound. This device is now on the Free plan.

跳过确认 (CI-safe)：

getwebp logout --force

JSON 输出：

getwebp logout --force --json

{
  "success": true,
  "data": {
    "message": "Device unbound. Switched to Free plan."
  }
}

失败的注销 (JSON)：

{
  "success": false,
  "status": "error",
  "error": "network_unreachable",
  "message": "Cannot reach server. Retry later or unbind via dashboard."
}

退出代码 #

代码	含义
`0`	所有文件处理成功
`1`	常规错误
`2`	部分失败（某些文件失败）
`3`	许可证 / 认证错误
`4`	网络错误

查看退出代码了解详细描述和重试指导。

JSON 错误代码 #

启用 --json 时，错误包括机器可读的 error 字段：

代码	含义	可重试
`missing_input`	未指定输入路径	否
`network_unreachable`	无法访问 API 服务器	是
`not_activated`	设备上无活跃许可证	否
`device_not_found`	设备已解绑	否
`invalid_token`	令牌已过期或已撤销	否
`unknown_error`	未分类的错误	是

查看 JSON 输出了解完整的输出架构。

层级对比 #

功能	免费	Pro ($39/年)
每次运行的文件数	20	无限制
处理速度	每个文件 3 秒延迟	即时
并行工作者	1 (串行)	自动 (CPU 核心数 - 1)
自定义 `--concurrency`	--	最多 32
`--recursive`	是	是
自定义 `--quality`	是	是
`--json` 输出	是	是
`--dry-run` / `--skip-existing`	是	是

在 getwebp.com/pricing 升级。

文档

GetWebP CLI 命令参考