Upgrade and Migration Guide

How to upgrade GetWebP CLI to a new version, change your plan tier, or move your license to a different device.

See also: Getting Started | Commands Reference | Troubleshooting

Table of Contents#

• Upgrade Your Plan (Free to Starter to Pro)
• Upgrade the CLI Version
  • Binary Download (All Platforms)
  • Verify the Upgrade
• Migrate to a New Device
  • Step 1 -- Deactivate the Old Device
  • Step 2 -- Install on the New Device
  • Step 3 -- Activate on the New Device
  • Emergency: Old Device Unavailable
• Config File Compatibility
  • Config Location
  • Machine-Bound Encryption
  • Upgrading Config Across Versions
• Breaking Changes by Version
  • v2.1.0 (2026-04-01)
  • v2.0.0 (2025-01-01)
• FAQ

Upgrade Your Plan (Free to Starter to Pro)#

GetWebP CLI works immediately on the Free plan. To unlock faster processing, parallel workers, and unlimited files per run, upgrade to Starter or Pro.

How Plan Upgrades Work#

Steps#

1. Purchase or upgrade your license at getwebp.com/pricing.
2. Activate the new license key on your device:

getwebp auth XXXX-XXXX-XXXX-XXXX

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

3. Confirm the upgrade took effect:

getwebp status

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

If you are upgrading from Starter to Pro with a new key, run getwebp auth with the new key. The old activation is replaced automatically -- there is no need to log out first.

Tip: Your existing license key may be upgraded in place (depending on how the upgrade was purchased). Check your email or dashboard for details.

Upgrade the CLI Version#

Binary Download (All Platforms)#

This is the standard upgrade path for all platforms.

1. Download the latest binary for your platform from the Releases page.

2. Replace the existing binary.

macOS / Linux:

# Download and rename
mv getwebp-macos-arm64 getwebp    # adjust for your platform
chmod +x getwebp
 
# Replace the existing binary
sudo mv getwebp /usr/local/bin/

If macOS blocks the new binary, remove the quarantine attribute:

xattr -cr /usr/local/bin/getwebp

Windows:

Replace getwebp.exe in the directory on your PATH (e.g., C:\Tools\getwebp.exe) with the newly downloaded file.

3. Verify the download integrity (optional but recommended):

# macOS / Linux
shasum -a 256 -c getwebp-macos-arm64.sha256

# Windows (PowerShell)
$expected = (Get-Content getwebp.exe.sha256).Split(' ')[0]
$actual   = (Get-FileHash getwebp.exe -Algorithm SHA256).Hash.ToLower()
if ($expected -eq $actual) { Write-Host "Verified OK" } else { Write-Host "MISMATCH" }

Verify the Upgrade#

getwebp --version

Expected output (example):

getwebp/1.0.1

Your license activation carries over automatically. No re-authentication is needed after a version upgrade -- the config file and stored token remain intact.

# Confirm your license is still active
getwebp status

Migrate to a New Device#

GetWebP licenses are bound to the device where they are activated. Each license has a device limit (visible via getwebp status). To move your license to a new machine, you must free the device slot on the old machine first.

Step 1 -- Deactivate the Old Device#

On the old device, run:

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.

This contacts the server, removes the device binding, and clears the local token. For scripts or CI, use --force to skip the confirmation prompt:

getwebp logout --force

Important: getwebp logout requires network access. If you cannot connect, see Emergency: Old Device Unavailable below.

Step 2 -- Install on the New Device#

Follow the standard installation steps for your platform. See Getting Started -- Installation.

Step 3 -- Activate on the New Device#

On the new device, run:

getwebp auth XXXX-XXXX-XXXX-XXXX

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

Verify:

getwebp status

Emergency: Old Device Unavailable#

If the old device is lost, broken, or otherwise inaccessible:

1. Go to your GetWebP Dashboard.
2. Find the device under your license and remove it manually.
3. Activate on the new device with getwebp auth.

If you have reached your device limit and cannot access the dashboard, contact support via the website.

Config File Compatibility#

Config Location#

GetWebP stores its configuration (license token and status cache) in a platform-specific directory:

You can override the config directory by setting the GETWEBP_CONFIG_DIR environment variable:

GETWEBP_CONFIG_DIR=/custom/path getwebp status

Machine-Bound Encryption#

The config file is encrypted using a key derived from your machine's hardware ID (via node-machine-id). This means:

• Config files cannot be copied between machines. A config file from one device will fail to decrypt on a different device.
• Do not back up config files for use on other machines. The token inside will be unreadable.
• If your machine ID changes (e.g., major hardware replacement, OS reinstall that changes the system UUID), the existing config may become unreadable. In that case, delete the config file and re-activate with getwebp auth.

If the machine ID cannot be read (e.g., in certain containerized environments), the CLI falls back to a key derived from the hostname and username. Changing either of these will invalidate the stored config.

Upgrading Config Across Versions#

• v2.0.0 to v2.1.0: No config migration required. The config schema is unchanged between these versions.
• Pre-2.0.0 to 2.0.0+: Version 2.0.0 introduced an entirely new config system. If you previously used a pre-2.0.0 version, the old config is ignored. Run getwebp auth to activate your license under the new system.

Breaking Changes by Version#

v2.1.0 (2026-04-01)#

Previously, Pro-tier users had recursive scanning enabled by default. Starting in v2.1.0, all tiers require the explicit -r flag.

Before (v2.0.0):

# Recursively processed subdirectories automatically (Pro)
getwebp convert ./images

After (v2.1.0+):

# Must pass -r explicitly
getwebp convert ./images -r

Other changes in v2.1.0 (non-breaking):

• New flags: --concurrency, --dry-run, --skip-existing, --verbose, --debug
• SIGINT (Ctrl+C) now performs graceful shutdown, cleaning up partial files
• macOS Intel binary now available
• SHA256 checksum files included in releases

v2.0.0 (2025-01-01)#

Version 2.0.0 was a complete rewrite. If you are upgrading from a pre-2.0.0 version:

FAQ#

Do I need to log out before upgrading the CLI version?#

No. Version upgrades do not affect your license. Simply replace the binary and your activation remains valid.

Can I run different CLI versions on the same machine?#

Yes, but only one binary should be on your PATH at a time. The config file is shared, so both versions would read the same license token. Avoid running very different major versions simultaneously.

What happens if I forget to log out before switching devices?#

Your license's device slots remain occupied. Use the GetWebP Dashboard to remove the old device remotely, then activate on the new device.

My config file seems corrupted after a hardware change. What do I do?#

Delete the config file and re-activate:

# macOS
rm ~/Library/Preferences/getwebp-nodejs/config.json
 
# Linux
rm ~/.config/getwebp-nodejs/config.json
 
# Windows (PowerShell)
Remove-Item "$env:APPDATA\getwebp-nodejs\config.json"

Then re-activate:

getwebp auth XXXX-XXXX-XXXX-XXXX

I upgraded my plan but getwebp status still shows the old tier.#

Run getwebp auth with the new (or same) license key to refresh the local token. If the license was upgraded in place, getwebp status may need a network connection to fetch the updated status from the server.

Links:

• Pricing -- purchase or upgrade your plan
• Dashboard -- manage devices and licenses
• Download -- get the latest binary
• Changelog -- full version history