GetWebP CLI Commands Reference

GetWebP CLI Commands Reference

Complete reference for all GetWebP CLI commands, flags, and output formats.

See also: README | Getting Started | Exit Codes | JSON Output

Quick Reference#

Global Flags#

These flags apply to all commands.

# Print version
getwebp --version
# Output: getwebp/1.0.1
 
# Show help
getwebp --help

getwebp <path>#

Convert one or more images to WebP or AVIF format. Original files are never modified or deleted.

Synopsis#

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

The positional [path] argument and the -i, --input flag are interchangeable. If both are provided, the positional argument takes precedence.

Flags#

Notes:

• On the Free plan, --concurrency is ignored. Processing is serial with a 3-second delay between files and a 20-file limit per run.
• Quality is clamped to the range 1--100. Invalid values fall back to 80.
• When --output is omitted, converted files are written next to the source files.
• Auto-quality (SSIM binary search) is WebP-only. --format avif always uses fixed quality (default 55).
• --format values are case-insensitive. Any other value exits with code 2.

Supported Formats#

Examples#

Convert a single image:

getwebp photo.png

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

Convert a directory with custom output:

getwebp ./images -o ./dist/images

High quality, skip already-converted files:

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

Recursive scan of subdirectories:

getwebp ./images -r

Parallel processing with 8 workers (Pro):

getwebp ./images --concurrency 8

Preview what would be converted (no writes):

getwebp ./images --dry-run

NDJSON output for CI/CD pipelines:

getwebp ./images --json

{"@timestamp":"2026-04-12T10:00:00.000Z","@level":"info","@message":"GetWebP CLI 1.3.0","@module":"getwebp.cli","type":"version","data":{"getwebp":"1.3.0","ui":"1"}}
{"@timestamp":"2026-04-12T10:00:01.234Z","@level":"info","@message":"Converted 1/1 files","@module":"getwebp.convert","type":"convert.completed","data":{"processed":1,"total":1,"successCount":1,"failedCount":0,"results":[{"file":"photo.jpg","outputPath":"/abs/path/photo.webp","originalSize":204800,"newSize":133120,"savedRatio":0.35,"saved":"35.0%","quality":82,"qualityMode":"auto","status":"success"}]}}

See JSON Output for the full NDJSON schema.

Convert to AVIF:

getwebp ./images --format avif --quality 55

Convert to AVIF with custom output directory:

getwebp ./images --format avif -o ./dist/avif

Using the -i flag instead of a positional argument:

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

Free Plan Behavior#

When no license is activated:

• Maximum 20 files per run. Remaining files are reported as skipped.
• 3-second delay between each file.
• --concurrency is ignored (serial processing only).

NDJSON output on Free plan when the file limit is reached emits a convert.truncated event. See JSON Output for the full schema.

getwebp auth#

Activate a license key to unlock Pro features. Binds the license to the current device.

Synopsis#

getwebp auth <license-key>

Flags#

Examples#

Activate a license:

getwebp auth XXXX-XXXX-XXXX-XXXX

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

Activate with JSON output:

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

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

Failed activation (JSON):

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

Purchase a license at getwebp.com/pricing.

getwebp status#

Display current license info, plan tier, expiry date, and device usage.

Synopsis#

getwebp status

Flags#

Examples#

Free plan (no license activated):

getwebp status

Version    : 1.0.1
Mode       : Free

Pro plan:

getwebp status

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

JSON output:

getwebp status --json

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

Free plan (JSON):

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

Cached status (offline, network unreachable):

When the API is unreachable but a cached JWT exists, status is returned from local cache:

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

getwebp logout#

Unbind the license from this device, freeing a device slot. Requires network access.

Synopsis#

getwebp logout [options]

Flags#

Note: In scripts and CI environments, use --force to skip the interactive confirmation prompt. When using --json, the confirmation prompt is also automatically skipped.

Examples#

Interactive logout:

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.

Skip confirmation (CI-safe):

getwebp logout --force

JSON output:

getwebp logout --force --json

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

Failed logout (JSON):

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

Exit Codes#

See Exit Codes for detailed descriptions and retry guidance.

JSON Error Codes#

When --json is enabled, errors include a machine-readable error field:

See JSON Output for the full output schema.

Tier Comparison#

Upgrade at getwebp.com/pricing.