Configuration

GetWebP CLI stores license tokens and status cache in an encrypted JSON file managed by the conf library. This guide covers file locations, environment variables, encryption behavior, and multi-device workflows.

Table of Contents#

• Config File Location
• Config File Contents
• Environment Variables
• Encryption and Machine Binding
• Multi-Device Usage
• Device Migration
• CI/CD Environments
• Troubleshooting

Config File Location#

GetWebP uses the conf npm package with projectName: 'getwebp', which delegates to platform-specific configuration directories via env-paths. The config file is named config.json.

On Linux, the path respects the XDG_CONFIG_HOME environment variable. If set, the file is stored at $XDG_CONFIG_HOME/getwebp-nodejs/config.json instead of the default ~/.config/ prefix.

Overriding the Config Directory#

Set the GETWEBP_CONFIG_DIR environment variable to store the config file in a custom directory:

# Linux / macOS
export GETWEBP_CONFIG_DIR=/opt/getwebp
getwebp status
# Config file: /opt/getwebp-nodejs/config.json
 
# Windows (PowerShell)
$env:GETWEBP_CONFIG_DIR = "C:\getwebp"
getwebp status
# Config file: C:\getwebp\config.json

When GETWEBP_CONFIG_DIR is set, it overrides the platform default completely. The directory is created automatically if it does not exist.

Locating Your Config File#

To confirm the actual path on your system:

# macOS / Linux
ls ~/Library/Preferences/getwebp/config.json  2>/dev/null  # macOS
ls ~/.config/getwebp/config.json               2>/dev/null  # Linux
 
# Windows (PowerShell)
Test-Path "$env:APPDATA\getwebp\Config\config.json"

Config File Contents#

The config file contains two fields, both managed automatically by CLI commands. You should not edit this file manually -- it is encrypted and direct modifications will corrupt it.

statusCache Object#

The status cache is updated each time getwebp status contacts the API server successfully. When the network is unreachable, the CLI falls back to the cached data and marks it with cached: true.

Environment Variables#

User-Configurable#

This is the only environment variable intended for end-user configuration.

Build-Time (Internal)#

These variables are embedded during the build process and are not intended for end users. They are documented here for completeness.

Warning: Overriding API_BASE_URL or JWT_PUBLIC_KEY at runtime will cause license validation failures unless you are running your own API server. These variables exist for internal development and testing only.

Encryption and Machine Binding#

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

1. At-rest encryption -- The JWT token is not stored in plaintext on disk.
2. Machine binding -- The config file cannot be decrypted on a different machine. Copying config.json to another computer will not transfer your license.

How the Encryption Key Is Derived#

Machine hardware ID  -->  SHA-256 hash  -->  encryption key

The hardware ID is sourced from:

• macOS: IOPlatformUUID from the IOKit registry
• Linux: /var/lib/dbus/machine-id or /etc/machine-id
• Windows: MachineGuid from the Windows registry

If the machine ID cannot be read (e.g., in a restricted container), the CLI falls back to a hash of hostname:username. In this fallback mode, renaming the host or switching users will invalidate the encrypted config.

Multi-Device Usage#

Starter and Pro licenses support multiple devices. The device limit depends on your plan:

Each device is identified by a SHA-256 hash of its hardware ID. To check how many device slots are in use:

getwebp status

Devices    : 2 / 3 used

You can also manage devices from the web dashboard at getwebp.com/dashboard.

Adding a New Device#

Activate using the same license key on the new machine:

getwebp auth XXXX-XXXX-XXXX-XXXX

If all device slots are occupied, the activation will fail. Free a slot first by logging out from an existing device (see below).

Removing a Device#

Run getwebp logout on the device you want to remove:

getwebp logout

This contacts the API server to unbind the device and clears the local config. The freed slot can then be used on another machine. If you no longer have access to the device, use the web dashboard to unbind it remotely.

Device Migration#

To move your license from one machine to another:

1. On the old machine, release the device slot:

   getwebp logout

2. On the new machine, activate with the same license key:

   getwebp auth XXXX-XXXX-XXXX-XXXX

Do not copy config.json between machines. The file is encrypted with a machine-specific key and cannot be decrypted on a different device. Always use getwebp logout + getwebp auth to migrate.

Lost Access to the Old Machine#

If you cannot run getwebp logout on the old machine (e.g., hardware failure):

1. Go to getwebp.com/dashboard.
2. Find the old device in your device list and unbind it.
3. Activate on the new machine with getwebp auth.

CI/CD Environments#

In CI/CD pipelines, each runner typically has a unique machine ID, which means each run would consume a device slot. For CI/CD use cases:

• Use GETWEBP_CONFIG_DIR to point to a persistent directory if your CI runner has persistent storage.
• Run getwebp logout --force at the end of a pipeline to release the device slot.
• Use --json output for machine-parseable results (see JSON Output).

# Example: GitHub Actions step
- run: |
    getwebp auth ${{ secrets.GETWEBP_LICENSE_KEY }}
    getwebp convert ./images -r --json
    getwebp logout --force

Note: Ephemeral CI runners (GitHub Actions, GitLab CI) generate a new machine ID on each run. If device slots are exhausted, unbind stale devices from the dashboard.

Troubleshooting#

"Token may become invalid if hostname changes"#

This warning appears when the CLI cannot read the hardware machine ID and falls back to hostname:username. Common causes:

• Running in a container without access to /var/lib/dbus/machine-id
• Restricted permissions on the machine ID file

Fix: Ensure /var/lib/dbus/machine-id or /etc/machine-id exists and is readable, or set a stable hostname.

Config file appears corrupted#

If the CLI fails to read the config after an OS reinstall or hardware change, the encryption key has changed and the old config cannot be decrypted.

Fix: 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\config.json"

Then activate again:

getwebp auth XXXX-XXXX-XXXX-XXXX

"JWT_PUBLIC_KEY was not injected at build time"#

This error means you are running a development or incorrectly built binary. Download the official binary from getwebp.com/download.

Related Documentation#