GetWebP CLI -- LLM Context Document

This document is optimized for AI agents (Cursor, Claude, Copilot, etc.) that need to understand and invoke the GetWebP CLI. Version: 1.0.1.

Product Description#

GetWebP CLI is a cross-platform command-line tool that batch-converts images (JPG, PNG, BMP, WebP) to optimized WebP format. It is distributed as a standalone binary for macOS (ARM64, x64), Linux (x64), and Windows (x64). The binary name is getwebp.

The CLI has three license tiers: Free, Starter, and Pro. Free tier is available without activation but limits conversion to 10 files per run with a 3-second delay between files and serial processing only. Starter and Pro tiers require license activation via getwebp auth <key> and unlock unlimited files, instant processing, and parallel workers (up to 32 concurrent). Licenses are purchased at getwebp.com/pricing.

The CLI uses JWT-based offline-first licensing. Once activated, the license is cached locally and works without a persistent network connection. The status command reports cached data when offline.

Original files are never modified or deleted. Output WebP files are written next to source files by default, or to a specified output directory.

All commands support --json for structured machine-readable output on stdout. Human-readable messages and warnings go to stderr. JSON output is a single line terminated by \n.

Command Quick-Reference#

convert#

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

Supported input formats: .jpg, .jpeg, .png, .bmp, .webp Output format: .webp (always)

auth#

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

Activates a license key and binds it to the current device.

status#

getwebp status [--json]

Shows version, plan tier, license suffix, expiry date, and device usage.

logout#

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

Unbinds license from device. Requires network. --force or --json skips interactive confirmation.

Global Flags#

Exit Codes#

JSON Output Schemas#

Envelope (all commands)#

{
  "success": boolean,
  "status"?: "success" | "error" | "partial",
  "error"?: string,         // machine-readable error code (on failure)
  "message"?: string,       // human-readable (on failure or partial)
  "data"?: object,          // command-specific payload
  "upgrade"?: { "url": string, "activateCommand": string }
}

convert -- success#

{
  "success": true,
  "status": "success",
  "total": number,
  "successCount": number,
  "failedCount": number,
  "results": [
    {
      "file": string,
      "status": "success",
      "originalSize": number,    // bytes
      "newSize": number,         // bytes
      "savedRatio": number,      // 0 to 1, negative if WebP is larger
      "saved": string            // e.g. "35.0%"
    }
  ]
}

convert -- partial failure#

Same shape as success but "success": false, "status": "error", and failed items have:

{ "file": string, "status": "error", "error": string }

convert -- Free plan limit reached#

{
  "success": true,
  "status": "partial",
  "message": string,
  "data": { "processed": number, "skipped": number },
  "upgrade": { "url": string, "activateCommand": string }
}

convert -- skipped item (--skip-existing)#

{ "file": string, "status": "skipped", "reason": "existing" }

auth -- success/error#

{ "success": true, "data": { "message": string } }
{ "success": false, "status": "error", "error": string, "message": string }

status -- active license#

{
  "success": true,
  "data": {
    "version": string,
    "mode": "free" | "starter" | "pro",
    "licenseKeySuffix"?: string,
    "expiresAt"?: string,          // ISO 8601
    "devicesUsed"?: number,
    "devicesLimit"?: number,
    "cached"?: true                // present only when offline
  }
}

logout -- success/error#

{ "success": true, "data": { "message": string } }
{ "success": false, "status": "error", "error": string, "message": string }

JSON Error Codes#

Common Usage Scenarios#

Convert all PNG files in a directory to WebP#

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

Convert all images recursively in a project's image folder#

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

High-quality conversion, skip already-converted files#

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

Preview what would be converted (no disk writes)#

getwebp convert ./images --dry-run

CI/CD pipeline: convert and fail on errors#

result=$(getwebp convert ./src/images -o ./dist/images -q 85 --json 2>/dev/null)
echo "$result" | jq -e '.success'

Check current license status programmatically#

getwebp status --json | jq -r '.data.mode'

Activate a license in CI#

getwebp auth "$GETWEBP_LICENSE_KEY" --json | jq -e '.success'

Deactivate license from device (non-interactive)#

getwebp logout --force --json

Parallel conversion with 8 workers (Starter/Pro)#

getwebp convert ./images --concurrency 8

Get total bytes saved from a conversion run#

getwebp convert ./images --json 2>/dev/null | jq '[.results[] | select(.status == "success") | (.originalSize - .newSize)] | add'

Tier Comparison#

Known Limitations#

1. Output format is WebP only. There is no option to convert to other formats.
2. Free tier: 10-file limit per run. Files beyond the limit are skipped, not queued.
3. Free tier: 3-second artificial delay per file. Cannot be bypassed without a license.
4. Free tier: --concurrency is ignored. Processing is always serial.
5. Logout requires network. The device cannot be unbound offline. Use the web dashboard as a fallback.
6. No streaming JSON. The convert command emits a single JSON object after all files are processed, not per-file events.
7. Quality is clamped to 1-100. Invalid values silently fall back to 80.
8. WebP-to-WebP re-encoding is supported but may increase file size. Check savedRatio for negative values.
9. macOS Gatekeeper may block the unsigned binary. Run xattr -cr getwebp to remove the quarantine attribute.
10. No stdin/stdout piping for image data. Input must be file paths; output is always written to disk.

Stderr Warnings#

The CLI may emit warnings to stderr regardless of --json. These are not part of the JSON stream. Suppress with 2>/dev/null. Examples:

warn: Free plan: max 10 files, 3s delay between each.
warn: No --output specified: converted files will be written next to source files.
warn: Conflict: a.png, a.jpg all map to a.webp -- only the last processed will survive

Constants (from source)#