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 convert#

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

Synopsis#

getwebp convert [path] [options]
getwebp convert -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 10-file limit per run.
• Quality is clamped to the range 1--100. Invalid values fall back to 80.
• When --output is omitted, .webp files are written next to the source files.

Supported Input Formats#

Examples#

Convert a single image:

getwebp convert photo.png

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

Convert a directory with custom output:

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

High quality, skip already-converted files:

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

Recursive scan of subdirectories:

getwebp convert ./images -r

Parallel processing with 8 workers (Starter/Pro):

getwebp convert ./images --concurrency 8

Preview what would be converted (no writes):

getwebp convert ./images --dry-run

JSON output for CI/CD pipelines:

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%"
    }
  ]
}

Using the -i flag instead of a positional argument:

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

Free Plan Behavior#

When no license is activated:

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

JSON output on Free plan when the file limit is reached:

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

getwebp auth#

Activate a license key to unlock Starter or 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! Starter plan unlocked.

Activate with JSON output:

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

{
  "success": true,
  "data": {
    "message": "Activated — Starter 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

Starter/Pro plan:

getwebp status

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

JSON output:

getwebp status --json

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

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.