GetWebP CLI JSON Output Reference

interface Envelope {
  '@timestamp': string    // RFC3339 UTC with ms precision, e.g. "2026-04-12T10:00:00.123Z"
  '@level': 'info' | 'warn' | 'error'
  '@message': string      // single-line human-readable summary
  '@module': string       // e.g. "getwebp.convert"
  type: string            // event discriminator (see per-command sections)
  data: object            // event payload (always present, {} if empty)
}

{"@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"}}

// data shape for convert.completed
interface ConvertCompletedData {
  processed: number       // total files attempted
  total: number           // same as processed
  successCount: number    // files converted successfully
  failedCount: number     // files that errored
  results: FileResult[]   // per-file details (see below)
}

// data shape for convert.truncated
interface ConvertTruncatedData {
  processed: number       // files actually converted
  skipped: number         // files skipped due to Free plan limit
  limit: number           // plan file limit (20 for Free)
  upgrade_url: string     // "https://getwebp.com/pricing"
}

interface ConvertFailedData {
  code: string            // machine-readable error code, e.g. "usage_error", "missing_input"
  hint?: string           // optional human-readable correction hint
}

// Successfully converted
interface SuccessResult {
  file: string            // input file path
  outputPath: string      // absolute path to the written output file (.webp or .avif)
  originalSize: number    // bytes
  newSize: number         // bytes
  savedRatio: number      // 0 to 1 (negative if output is larger than original)
  saved: string           // human-friendly percentage, e.g. "35.0%"
  quality: number         // actual quality used
  qualityMode: 'auto' | 'fixed'  // auto = SSIM binary search; fixed = --quality or AVIF
  ssim?: number           // SSIM score (auto mode only)
  status: "success"
}
 
// Conversion failed
interface ErrorResult {
  file: string
  status: "error"
  error: string           // e.g. "Decode failed: Unsupported format"
}
 
// Skipped (--skip-existing or output-equals-input)
interface SkipResult {
  file: string
  status: "skipped"
  reason: "existing"
}

// Success
interface AuthSuccessResponse {
  success: true
  data: {
    message: string   // e.g. "Activated — Pro plan unlocked"
  }
}
 
// Failure
interface AuthErrorResponse {
  success: false
  status: "error"
  error: "unknown_error"
  message: string         // server-provided error description
}

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

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

// Free plan (never activated)
interface StatusFreeResponse {
  success: true
  data: {
    version: string       // e.g. "1.0.1"
    mode: "free"
  }
}
 
// Active license, online (full status from server)
interface StatusOnlineResponse {
  success: true
  data: {
    version: string
    mode: "pro"
    licenseKeySuffix: string    // last 4 characters, e.g. "A1B2"
    expiresAt: string           // ISO 8601, e.g. "2027-04-01T00:00:00.000Z"
    devicesUsed: number
    devicesLimit: number
  }
}
 
// Active license, server cache (server returned data with cached flag)
interface StatusCachedResponse {
  success: true
  data: {
    version: string
    mode: "pro"
    licenseKeySuffix: string
    expiresAt: string
    cached: true                // indicates data is from local cache
  }
}
 
// Token exists but server unreachable and no status cache (JWT-only fallback)
interface StatusOfflineResponse {
  success: true
  data: {
    version: string
    mode: "pro"
    cached: true
    expiresAt?: string          // ISO 8601 (from JWT exp claim)
  }
}

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

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

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

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

// Success
interface LogoutSuccessResponse {
  success: true
  data: {
    message: "Device unbound. Switched to Free plan."
  }
}
 
// Failure
interface LogoutErrorResponse {
  success: false
  status: "error"
  error: string       // machine-readable code (see table below)
  message: string     // human-readable description
}

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

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

{
  "success": false,
  "status": "error",
  "error": "not_activated",
  "message": "No active license on this device."
}

# Extract the convert.completed event
getwebp ./images --json | grep '"convert.completed"'
 
# Check if all conversions succeeded (failedCount == 0)
getwebp ./images --json \
  | grep '"convert.completed"' \
  | jq '.data.failedCount == 0'
 
# Get total bytes saved across all successful files
getwebp ./images --json \
  | grep '"convert.completed"' \
  | jq '[.data.results[] | select(.status == "success") | (.originalSize - .newSize)] | add'
 
# List failed files
getwebp ./images --json \
  | grep '"convert.completed"' \
  | jq '[.data.results[] | select(.status == "error") | .file]'
 
# Get output paths for all successfully converted files
getwebp ./images --json \
  | grep '"convert.completed"' \
  | jq '[.data.results[] | select(.status == "success") | .outputPath]'
 
# Get average compression ratio
getwebp ./images --json \
  | grep '"convert.completed"' \
  | jq '[.data.results[] | select(.status == "success") | .savedRatio] | add / length'
 
# Exit with error if any file failed
getwebp ./images --json \
  | grep '"convert.completed"' \
  | jq -e '.data.failedCount == 0' > /dev/null
 
# Check if Free plan limit was hit
getwebp ./images --json \
  | grep '"convert.truncated"' \
  | jq '.data.skipped'
 
# Extract file names and sizes as CSV
getwebp ./images --json \
  | grep '"convert.completed"' \
  | jq -r '.data.results[] | select(.status == "success") | [.file, .outputPath, .originalSize, .newSize, .saved] | @csv'

# Get current plan
getwebp status --json | grep '"status.reported"' | jq -r '.data.mode'
 
# Check if license is active (not free)
getwebp status --json | grep '"status.reported"' | jq '.data.mode != "free"'
 
# Get expiry date
getwebp status --json | grep '"status.reported"' | jq -r '.data.expiresAt // "N/A"'
 
# Check device usage
getwebp status --json | grep '"status.reported"' | jq '"\(.data.devicesUsed // "?") / \(.data.devicesLimit // "?")"'

# Activate and check result
getwebp auth XXXX-XXXX-XXXX-XXXX --json | grep '"auth.completed"' | jq -e '.'
 
# Logout (--json skips confirmation automatically)
getwebp logout --json | grep '"logout.completed"' | jq -e '.'

#!/usr/bin/env bash
set -euo pipefail
 
getwebp ./src/images -o ./dist/images --quality 85 --json > /tmp/gw_out.ndjson
 
completed=$(grep '"convert.completed"' /tmp/gw_out.ndjson)
 
if [ -z "$completed" ]; then
  echo "Conversion did not complete" >&2
  cat /tmp/gw_out.ndjson >&2
  exit 1
fi
 
failed=$(echo "$completed" | jq '.data.failedCount')
if [ "$failed" -gt 0 ]; then
  echo "Conversion failed for $failed file(s):" >&2
  echo "$completed" | jq -r '.data.results[] | select(.status == "error") | "  \(.file): \(.error)"' >&2
  exit 1
fi
 
total=$(echo "$completed" | jq -r '.data.total')
saved=$(echo "$completed" | jq '[.data.results[] | select(.status == "success") | (.originalSize - .newSize)] | add')
echo "Converted $total images, saved $saved bytes total"

getwebp ./images --json 2>/dev/null