GetWebP CLI 命令参考

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

快速参考 #

命令	描述
`getwebp convert [path]`	将图像转换为 WebP 格式
`getwebp watch [...paths]`	监视目录并在变更时自动转换（Pro）
`getwebp auth <license-key>`	激活许可证密钥
`getwebp status`	显示许可证和版本信息
`getwebp logout`	从此设备解绑许可证

全局标志 #

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

标志	别名	描述	默认值
`--version`	`-V`	打印 CLI 版本并退出	--
`--help`	`-h`	显示帮助文本并退出	--
`--json`	`-j`	在 stdout 上输出 NDJSON 事件（人类消息转到 stderr）	关闭
`--verbose`	`-v`	启用详细输出	关闭
`--quiet`	`-q`	在 stderr 上抑制 info 和 warn；错误仍会打印	关闭
`--debug`	--	启用调试输出（隐含 `--verbose`）	关闭
`--force`	`-f`	跳过交互式确认提示	关闭

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

重大变更 (v1.2.0)： -v 此前是 --version 的别名，现在是 --verbose。请使用 -V（大写）来打印版本。

`getwebp convert`#

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

概要 #

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

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

标志 #

标志	别名	描述	默认值	层级
`<path>` (位置)	--	要转换的输入文件或目录	--	所有
`--input <path>`	`-i`	输入文件或目录（位置参数的替代）	--	所有
`--output <path>`	`-o`	已转换文件的输出目录	与源相同的目录	所有
`--quality <number>`	--	WebP 质量，1-100。覆盖自动质量。	auto	所有
`--no-auto-quality`	--	禁用 SSIM 自动质量；使用固定质量 80	关闭	所有
`--recursive`	`-r`	递归处理子目录中的图像	关闭	所有
`--concurrency <number>`	--	并行工作者数，最多 32	CPU 核心数 - 1	Pro
`--dry-run`	--	预览将被转换的文件（不写入）	关闭	所有
`--skip-existing`	--	如果输出路径已存在 `.webp` 文件则跳过	关闭	所有
`--manifest <path>`	--	将 JSON 资源指纹清单写入指定路径	--	所有

注意：

质量：默认情况下，GetWebP 使用基于 SSIM 的自动质量，找到与源文件视觉上完全相同的最小 WebP。使用 --quality <N> 指定固定质量。使用 --no-auto-quality 在不指定数字的情况下使用固定质量 80。
在免费计划上，--concurrency 被忽略。处理是串行的，文件之间有 3 秒延迟，每次运行限制 20 个文件。
-q 是全局 --quiet 的别名，不是 --quality 的别名。

支持的输入格式 #

输入	输出
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 --quality 95 --skip-existing

递归扫描子目录：

getwebp convert ./images -r

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

getwebp convert ./images --concurrency 8

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

getwebp convert ./images --dry-run

CI/CD 管道的 NDJSON 输出：

getwebp convert ./images --json

{"@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"}}
{"@timestamp":"2026-04-11T10:00:01.000Z","@level":"info","@message":"Converted 3/3 files","@module":"getwebp.convert","type":"convert.completed","data":{"processed":3,"total":3,"successCount":3,"failedCount":0,"results":[{"file":"photo.jpg","originalSize":204800,"newSize":133120,"savedRatio":0.35,"saved":"35.0%","quality":78,"qualityMode":"auto","status":"success"}]}}

写入资源指纹清单：

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

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

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

免费计划行为 #

当未激活许可证时：

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

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

{"@timestamp":"...","@level":"warn","@message":"Processed 20/25 images — Free plan limit reached. 5 remaining.","@module":"getwebp.convert","type":"convert.truncated","data":{"processed":20,"skipped":5,"limit":20,"upgrade_url":"https://getwebp.com/pricing"}}

`getwebp watch`#

仅限 Pro 计划。 自 v1.2.0 起可用。

监视一个或多个目录的文件变更，并自动将新的或修改的图像转换为 WebP。作为前台守护程序运行，直到按 Ctrl+C 停止。

概要 #

getwebp watch [paths...] [options]

标志 #

标志	别名	描述	默认值
`--output <path>`	`-o`	将转换后的文件镜像到此目录（保留目录树）	与源相同的目录
`--quality <number>`	--	固定 WebP 质量，1-100	auto
`--no-auto-quality`	--	禁用 SSIM 自动质量；使用固定质量 80	关闭
`--concurrency <number>`	--	覆盖并行工作者数量	`max(2, ceil(cpus / 4))`
`--stability-threshold <ms>`	--	文件写入稳定性检测窗口	1000ms
`--backfill`	--	启动时处理所有现有文件，然后再开始监视	关闭
`--no-color`	--	禁用 ANSI 颜色	关闭

示例 #

监视单个目录：

getwebp watch ./images

带输出目录监视（镜像树）：

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

启动时回填现有文件，然后监视：

getwebp watch ./images --backfill

用于 CI/代理的 NDJSON 输出：

getwebp watch ./images --json

{"@timestamp":"...","@level":"info","@message":"GetWebP CLI 1.2.1","@module":"getwebp.cli","type":"version","data":{"getwebp":"1.2.1","ui":"1"}}
{"event":"banner","ts":"...","root":"/abs/path/to/images","recursive":true,"concurrency":4,"stability_ms":1000,"existing_unconverted":0,"gitignore":false,"excluded_default":["node_modules",".git","dist"]}
{"event":"converted","ts":"...","input":"/abs/path/images/photo.jpg","output":"/abs/path/images/photo.webp","original_size":204800,"new_size":133120,"saved_ratio":0.35,"quality":78,"quality_mode":"auto","duration_ms":450}
{"event":"heartbeat","ts":"...","queue_depth":0,"in_flight":0,"processed_total":1,"errors_total":0}

大多数 watch 事件使用带有 event 和 ts 字段的扁平格式。heartbeat 事件每 30 秒在空闲期间发出一次。完整的 watch 事件架构请参阅 JSON 输出。

`getwebp auth`#

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

概要 #

getwebp auth <license-key>

示例 #

激活许可证：

getwebp auth XXXX-XXXX-XXXX-XXXX

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

使用 NDJSON 输出激活：

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

{"@timestamp":"...","@level":"info","@message":"GetWebP CLI 1.2.1","@module":"getwebp.cli","type":"version","data":{"getwebp":"1.2.1","ui":"1"}}
{"@timestamp":"...","@level":"info","@message":"Activated — Pro plan unlocked","@module":"getwebp.auth","type":"auth.completed","data":{"plan":"pro"}}

失败的激活 (NDJSON)：

{"@timestamp":"...","@level":"error","@message":"Activation failed: license_invalid","@module":"getwebp.auth","type":"auth.failed","data":{"code":"license_invalid","hint":"license_invalid"}}

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

`getwebp status`#

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

概要 #

getwebp status

示例 #

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

getwebp status

Version    : 1.2.1
Mode       : Free

Pro 计划：

getwebp status

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

NDJSON 输出：

getwebp status --json

{"@timestamp":"...","@level":"info","@message":"GetWebP CLI 1.2.1","@module":"getwebp.cli","type":"version","data":{"getwebp":"1.2.1","ui":"1"}}
{"@timestamp":"...","@level":"info","@message":"Pro plan","@module":"getwebp.status","type":"status.reported","data":{"version":"1.2.1","plan":"pro","licenseKeySuffix":"A1B2","expiresAt":"2027-04-01T00:00:00.000Z","devicesUsed":1,"devicesLimit":5}}

`getwebp logout`#

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

概要 #

getwebp logout [options]

标志 #

标志	别名	描述	默认值
`--force`	`-f`	跳过交互式确认提示	关闭
`--json`	`-j`	NDJSON 输出	关闭

注意： 在脚本和 CI 环境中，使用 --force 跳过交互式确认提示。--json 单独使用不会跳过确认——它会以退出码 2 退出（UsageError: confirmation_required_in_json_mode）。非交互式场景必须同时使用 --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

NDJSON 输出：

getwebp logout --force --json

{"@timestamp":"...","@level":"info","@message":"GetWebP CLI 1.2.1","@module":"getwebp.cli","type":"version","data":{"getwebp":"1.2.1","ui":"1"}}
{"@timestamp":"...","@level":"info","@message":"Device unbound. Switched to Free plan.","@module":"getwebp.logout","type":"logout.completed","data":{}}

退出代码 #

代码	名称	含义
`0`	Success	所有操作成功完成
`1`	GenericError	未分类的错误
`2`	UsageError	无效参数（未知标志、缺少必需参数、错误的值）
`3`	PartialFailure	某些文件成功，某些失败
`4`	AuthError	许可证无效、过期或设备限制已超
`5`	NetworkError	API 不可访问或超时
`6`	FreeLimitReached	免费层级 20 文件限制已达（文件被跳过）
`75`	LicenseRevokedMidSession	许可证在 `watch` 会话期间过期或被撤销
`76`	DiskFull	`watch` 会话期间磁盘满，重试预算耗尽
`130`	SIGINT	Ctrl+C
`143`	SIGTERM	进程被终止

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

JSON 错误代码 #

启用 --json 时，错误事件包括机器可读的 data.code 字段：

`data.code`	含义	可重试
`missing_input`	未指定输入路径	否
`license_invalid`	许可证密钥未被识别	否
`license_expired`	许可证已过期	否
`device_limit_exceeded`	所有设备插槽均在使用中	否
`activation_failed`	服务器拒绝激活	否
`network_unreachable`	无法访问 API 服务器	是
`no_matches`	未找到受支持的图像	否
`config_write_failed`	无法将令牌写入磁盘	否
`license_revoked_startup`	会话开始前许可证已被撤销	否
`license_revoked_mid_session`	watch 会话期间许可证被撤销	否

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

层级对比 #

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

在 getwebp.com/pricing 升级。