License Setup

Free Tier

The Free tier requires no license. Install pageflare and run it — Free features are available immediately with no sign-up required.

Free features include: HTML/CSS/JS minification, JavaScript deferral, lazy loading, image dimension injection, font-display: swap, and preconnect hints.

Activating a Pro License

Interactive Login

Run the login command to open a browser-based authentication flow:

pageflare --login

This will:

1. Open your default browser to the pageflare login page
2. Authenticate with your pageflare account
3. Save a license token to ~/.config/pageflare/license.json

After login, Pro features are automatically unlocked for all subsequent pageflare runs on that machine.

License File

The license token is stored at:

~/.config/pageflare/license.json

The file format is:

{
  "token": "your-license-token-here"
}

You can inspect this file at any time to verify the token is present. Do not edit it manually — use pageflare --login to refresh or update the token.

License in CI/CD

For automated environments (CI/CD pipelines, servers, Docker containers), use the PAGEFLARE_LICENSE environment variable instead of the license file.

export PAGEFLARE_LICENSE=your-license-token
pageflare dist/ --output dist/

Store the token as a secret in your CI provider — never commit it to source control.

See the CI/CD integration guide for provider-specific instructions.

License Resolution Order

Pageflare resolves the license by checking the following locations in order, stopping at the first valid token found:

Priority	Source	Details
1 (highest)	PAGEFLARE_LICENSE environment variable	Checked first, takes precedence over all other sources
2	~/.config/pageflare/license.json	Written by pageflare --login
3 (lowest)	Free tier	Used when no token is found

This ordering means you can always override a local license file with the environment variable — useful for testing different license tiers or using a different token in CI.

Verification

To check which license tier is active, run pageflare with --log info:

pageflare dist/ --log info

The log output includes the resolved license tier (free or pro) and which Pro features are enabled or skipped.

Pro-Only Features

The following configuration options require a Pro license and are silently skipped on the Free tier:

• self_host_google_fonts
• font_unicode_range
• speculation_rules
• spa_mode
• critical_css
• defer_background_images
• youtube_facades
• remove_wp_bloat
• platform_images
• hash_filenames

You can safely set these to true in your config file even on Free — they are ignored without error and will activate automatically once a Pro license is detected.

License Expiry and Grace Period

When a Pro license expires, pageflare enters a grace period during which Pro features continue to work. This prevents an expired license from breaking your pipeline unexpectedly.

During the grace period:

• All Pro features remain active
• A warning is logged at the warn level on each run

After the grace period ends, the license falls back to the Free tier. Pro-only features are skipped until the license is renewed.

To renew, log in again:

pageflare --login

Or update the PAGEFLARE_LICENSE environment variable with your new token.

Troubleshooting

Pro features are not activating

1. Check that the license token is present: cat ~/.config/pageflare/license.json
2. Verify the PAGEFLARE_LICENSE variable is set in CI: echo $PAGEFLARE_LICENSE
3. Run with --log info to see the resolved tier in the log output
4. Check that your license is not expired in the pageflare dashboard

Login command does not open a browser

In headless environments (SSH sessions, Docker), the browser cannot open automatically. Copy the URL printed to the terminal, open it in your browser manually, complete the login, and the token will be saved once authentication completes.