Exit Codes

GetWebP CLI uses semantic exit codes so shell scripts and CI pipelines can react to different failure modes without parsing output text.

Reference Table#

Detailed Scenarios#

Exit 0 -- Success#

• All images converted without error.
• No matching files found (empty input directory). The CLI treats this as a no-op success.
• getwebp status completes normally.
• getwebp auth <key> activates successfully.
• getwebp logout unbinds successfully.

Exit 1 -- Generic Error#

• No input path provided (getwebp convert with no arguments).
• License activation fails (getwebp auth <invalid-key>).
• Logout fails (e.g. not_activated, device_not_found).
• Uncaught exception or unhandled promise rejection.

Handling: Check stderr (or JSON message field with --json) for details. Usually not retryable without user action.

Exit 2 -- Partial Failure#

• A batch conversion where some files converted and others failed (e.g. corrupt input, permission denied on specific files).
• The resolveExitCode() function returns 2 when any result has status: "error".

Handling: Parse --json output to identify which files failed. Retry only the failed files, or investigate per-file errors.

Exit 3 -- Auth Error#

• License key is invalid or revoked.
• License has expired.
• Device fingerprint does not match the activation record.

Handling: Re-activate with getwebp auth <key>, renew the license at getwebp.com/pricing, or check device bindings at getwebp.com/dashboard.

Exit 4 -- Network Error#

• Cannot reach the GetWebP API server.
• Request timed out.

Handling: Retryable. Wait and retry with exponential backoff. Check network connectivity and firewall rules.

Special Exit Code#

Shell Script Examples#

Basic: fail on any error#

#!/bin/bash
set -e
 
getwebp convert ./images -o ./dist
echo "All images converted."

Branching on exit code#

#!/bin/bash
 
getwebp convert ./images --json > results.json
code=$?
 
case $code in
  0)
    echo "All images converted successfully."
    ;;
  1)
    echo "Error: check arguments or license." >&2
    exit 1
    ;;
  2)
    echo "Warning: some files failed. Check results.json for details." >&2
    # Pipeline continues -- partial output is still usable
    ;;
  3)
    echo "License error. Re-activate with: getwebp auth <key>" >&2
    exit 1
    ;;
  4)
    echo "Network error. Retrying in 30s..." >&2
    sleep 30
    getwebp convert ./images --json > results.json
    ;;
  *)
    echo "Unexpected exit code: $code" >&2
    exit 1
    ;;
esac

CI pipeline: retry on network errors#

#!/bin/bash
MAX_RETRIES=3
RETRY_DELAY=10
 
for i in $(seq 1 $MAX_RETRIES); do
  getwebp convert ./images -o ./dist --json > results.json
  code=$?
 
  if [ $code -eq 0 ]; then
    echo "Success on attempt $i."
    exit 0
  elif [ $code -eq 4 ] && [ $i -lt $MAX_RETRIES ]; then
    echo "Network error. Retry $i/$MAX_RETRIES in ${RETRY_DELAY}s..." >&2
    sleep $RETRY_DELAY
    RETRY_DELAY=$((RETRY_DELAY * 2))
  else
    echo "Failed with exit code $code on attempt $i." >&2
    exit $code
  fi
done
 
exit 1

GitHub Actions example#

- name: Convert images
  run: |
    getwebp convert ./src/images -o ./dist/images --json > conversion.json
  continue-on-error: true
 
- name: Check conversion result
  run: |
    code=${PIPESTATUS[0]:-$?}
    if [ "$code" -eq 2 ]; then
      echo "::warning::Partial conversion failure -- check conversion.json"
    elif [ "$code" -ne 0 ]; then
      echo "::error::getwebp exited with code $code"
      exit 1
    fi

JSON Output and Exit Codes#

When using --json, the exit code and JSON payload work together:

The JSON error field provides a machine-readable error code (e.g. missing_input, network_unreachable, invalid_token). See json-output.md for the full JSON schema.

See Also#

• README -- overview and quick start
• Commands Reference -- all commands and options
• JSON Output -- structured output schema for CI and AI agents