@pageflare/cli

Optimize static site output for PageSpeed. Pageflare processes your SSG build output (HTML, CSS, JS, images) and applies production-grade optimizations.

GitHub Action

Add one step to your workflow — no install needed:

- uses: getappz/pageflare-cli@v1

With options:

- uses: getappz/pageflare-cli@v1
  with:
    args: "dist -o optimized --platform vercel"

| Input | Default | Description | |-------|---------|-------------| | version | latest | CLI version to install | | args | | Arguments passed to pageflare optimize |

Install

npm install -g @pageflare/cli

Or as a dev dependency:

npm install -D @pageflare/cli

Usage

# Optimize current directory
pageflare

# Optimize a specific build directory
pageflare dist

# Write optimized files to a separate output directory
pageflare dist -o optimized

# Optimize the build directory in place (overwrite files in dist/)
pageflare dist -o dist

# Wipe the output directory before writing (full reset; refuses if input == output)
pageflare dist -o optimized --clean-output

# Build pipeline integration — opt into GEO + SEO + audit during optimize
pageflare dist -o dist --with-geo --with-seo --with-audit
pageflare dist -o dist --with-pwa                     # generate manifest/SW/icons too
pageflare dist -o dist --fail-on-broken-refs          # exit non-zero on internal 404s

# Skip the browser-driven extractor (for CI environments without Chrome)
pageflare dist --no-browser

# Generate a config file
pageflare init

# Output manifest as JSON
pageflare dist --json

# Audit site for performance issues
pageflare audit dist

# Audit AI-readiness (GEO score) — auto-classifies as Content / API / All
pageflare geo audit --path dist/
pageflare geo audit --url https://example.com
pageflare geo audit --path dist/ --format github --badge

# Force a profile, or explain which signals drove auto-classification
pageflare geo audit --path dist/ --profile content
pageflare geo audit --path dist/ --explain-profile

# Auto-fix GEO issues (deterministic, no API key — requires Solo license)
pageflare geo fix dist/ --auto
pageflare geo fix dist/ --auto --profile api   # API/app sites only get API/MCP/agent-card templates

# Audit SEO (technical SEO score, free)
pageflare seo audit dist/

# Auto-fix SEO issues (deterministic — requires Solo license)
pageflare seo fix dist/ --auto

# PWA: generate manifest + service worker + icons locally (free)
pageflare pwa build

# Update to the latest version
pageflare upgrade

Reference

Command Overview:

• pageflare↴
• pageflare optimize↴
• pageflare audit↴
• pageflare init↴
• pageflare login↴
• pageflare logout↴
• pageflare upgrade↴
• pageflare geo↴
• pageflare geo audit↴
• pageflare geo fix↴
• pageflare geo run↴
• pageflare seo↴
• pageflare seo audit↴
• pageflare seo fix↴
• pageflare sites↴
• pageflare sites add↴
• pageflare sites list↴
• pageflare sites remove↴
• pageflare sites prune↴
• pageflare sites set↴
• pageflare sites pages↴
• pageflare sites pages list↴
• pageflare sites pages label↴
• pageflare sites pages exclude↴
• pageflare schedule↴
• pageflare schedule add↴
• pageflare schedule list↴
• pageflare schedule remove↴
• pageflare schedule pause↴
• pageflare schedule resume↴
• pageflare studio↴
• pageflare speed↴
• pageflare pwa↴
• pageflare pwa init↴
• pageflare pwa build↴
• pageflare pwa config↴
• pageflare pwa config set↴
• pageflare pwa disable↴
• pageflare pwa push↴
• pageflare pwa push send↴
• pageflare pwa push list↴
• pageflare pwa stats↴
• pageflare deploy↴

pageflare

Optimize static site output for PageSpeed

Usage: pageflare [OPTIONS] [COMMAND]

With no subcommand, runs 'optimize' by default.

Examples: pageflare Optimize current directory pageflare init Generate config file pageflare optimize --help Show optimize options pageflare upgrade Upgrade to latest version pageflare speed https://example.com Measure page speed

Subcommands:

• optimize — Optimize a static site directory (default)
• audit — Audit a static site (performance + SEO + GEO)
• init — Generate a pageflare.jsonc config file
• login — Authenticate and activate a Pro license
• logout — Remove license and deactivate this machine
• upgrade — Upgrade to the latest version of pageflare
• geo — Audit and fix AI-readiness (GEO)
• seo — SEO audit and fix tools
• sites — Manage monitored sites
• schedule — Manage scan schedules
• studio — Launch Pageflare Studio dashboard
• speed — Measure page speed via Google PageSpeed Insights
• pwa — PWA configuration and management
• deploy — Optimize and deploy to platform (vercel, netlify, cloudflare-pages)

Options:

• --log <LOG> — Set log level (off, error, warn, info, debug, trace)

  Default value: warn

• --json — Output results as JSON

pageflare optimize

Optimize a static site directory (default)

Usage: pageflare optimize [OPTIONS] [INPUT]

Arguments:

• <INPUT> — Path to the SSG output directory to process

  Default value: .

Options:

• -o, --output <OUTPUT> — Output directory. If omitted, writes to <input>/.appz/output/static/

• --json — Output manifest as JSON instead of summary table

• --force — Force reprocessing even if no files have changed

• --clean-output — Clean the output directory before writing. Removes every file and subdirectory inside the output dir at the start of the run. Use after pageflare-side changes that rename or drop files (e.g. content-hashed filenames, framework upgrade) to avoid stale leftovers from prior builds. Refuses to run when output is in-place — that would nuke the source

• -c, --config <CONFIG> — Path to config file. Defaults to <input>/pageflare.jsonc

• --login — Log in to activate your Pro license

• --platform <PLATFORM> — Deployment platform for image optimization (auto, vercel, netlify, cloudflare-pages, none)

• --prod — Production build. Enables platform CDN image rewrites

• --no-progress — Disable progress spinners (auto-detected in non-TTY environments)

• --with-geo — Run GEO (agent-readiness + crawler discovery) optimizations: - /sitemap.xml - /robots.txt + /llms.txt + /llms-full.txt + per-page .md - /.well-known/agent-card.json (A2A) - /.well-known/mcp/server-card.json - /.well-known/agent-skills/index.json - /.well-known/api-catalog (RFC 9727) - /ai/summary.json + /ai/faq.json

  Default optimize is a pagespeed optimizer; this flag is needed unless you explicitly enable sitemap/llm in your pageflare.jsonc. Non-destructive — skips any file already present in the source.

• --with-seo — Run SEO HTML injections during build (idempotent — never overwrites author-supplied tags): - when missing - when missing - derived from page url - basic OG tags (og:title, og:url, og:type) from page title

  Page-level only. Title text and meta-description content are author concerns — use pageflare seo fix for LLM-driven content fixes.

• --with-audit — Run audit checks during build and emit audit.json to the output dir. Idempotent — overwrites previous audit.json

• --with-pwa — Run PWA build (manifest, service worker, icons) after the main pipeline finishes. Reads pageflare.pwa.json from the project root

• --fail-on-broken-refs — Exit with non-zero status when broken references (404 internal links) are detected. Off by default so CI doesn't break on legacy content; turn on to gate deploys on link integrity

• --no-browser — Disable all browser-rendering features unconditionally. Forces pageflare onto the heuristic fallback paths — byte-position LCP detection, source-order font preload, legacy critical-CSS inliner — regardless of which features would otherwise run. Use this in environments where no browser is available, when CI restrictions block the auto-install prompt, or to deliberately compare optimized output against the heuristic baseline.

  When set, this suppresses the default critical-CSS apply pass and forces every render-pass-driven config flag off (font_preload_from_render, image_preload_from_render, content_visibility_lazy_render). The static-analysis fallback paths (critters-rs critical CSS, byte-position LCP heuristic, source-order font preload) take over.

pageflare audit

Audit a static site (performance + SEO + GEO)

Usage: pageflare audit [OPTIONS] [INPUT]

Arguments:

• <INPUT> — Path to the static site output directory

  Default value: .

Options:

• --json — Output findings as JSON instead of terminal summary

• --no-report — Skip HTML report generation

• -o, --output <OUTPUT> — Custom path for HTML report

• -c, --config <CONFIG> — Path to config file

• --platform <PLATFORM> — Deployment platform (auto, vercel, netlify, cloudflare-pages, none)

• --fail-under <FAIL_UNDER> — Exit with code 2 if any audit score falls below this threshold

• --fail-on-finding <FAIL_ON_FINDING> — Exit with code 2 when any performance finding at or above this severity exists. One of: error, warning, info. Independent of --fail-under (which gates SEO/GEO scores)

  Possible values: error, warning, info

• --no-save — Skip auto-saving to monitor DB

pageflare init

Generate a pageflare.jsonc config file

Usage: pageflare init [INPUT]

Arguments:

• <INPUT> — Path to the directory to generate config in

  Default value: .

pageflare login

Authenticate and activate a Pro license

Usage: pageflare login

pageflare logout

Remove license and deactivate this machine

Usage: pageflare logout

pageflare upgrade

Upgrade to the latest version of pageflare

Usage: pageflare upgrade [OPTIONS]

Command Alias: up

Options:

• --force — Force reinstall even if already on latest version

pageflare geo

Audit and fix AI-readiness (GEO)

Usage: pageflare geo <COMMAND>

Subcommands:

• audit — Audit site for AI-readiness score
• fix — Fix GEO issues using an LLM (Pro license)
• run — Audit + apply deterministic fixes in one step (equivalent to geo fix --auto). For LLM-driven patches, use geo fix

pageflare geo audit

Audit site for AI-readiness score

Usage: pageflare geo audit [OPTIONS] [INPUT]

Arguments:

• <INPUT> — Path to the site directory (project root or build output)

  Default value: .

Options:

• --url <URL> — Single URL to audit (fetches live, overrides path input)

• --base-url <BASE_URL> — Base URL for path mode (for robots.txt/llms.txt checks)

• --max-pages <MAX_PAGES> — Maximum number of pages to audit

• --format <FORMAT> — Output format: json, table, markdown, github, html, sarif

  Default value: table

• -o, --output <OUTPUT> — Write report to file instead of stdout

• --fail-under <FAIL_UNDER> — Exit code 2 if score is below this threshold (for CI)

• --verbose — Show all rules including passed ones

• --badge — Output badge snippets (Markdown, HTML) after the audit

• --no-save — Skip auto-saving to monitor DB

• --fail-on-finding <FAIL_ON_FINDING> — Exit with code 2 when any finding at or above this severity exists. One of: critical, warning, info. Independent of --fail-under (which gates on score)

  Possible values: critical, warning, info

• --profile <PROFILE> — Profile filter: auto (classify), all, content, api

  Default value: auto

  Possible values: auto, all, content, api

• --explain-profile — Print resolved profile + classifier signals to stderr

pageflare geo fix

Fix GEO issues using an LLM (Pro license)

Usage: pageflare geo fix [OPTIONS] [INPUT]

Arguments:

• <INPUT> — Path to the site directory (project root or build output)

  Default value: .

Options:

• -o, --output <OUTPUT> — Output directory. If omitted, uses resolved output dir

• --auto — Run deterministic fixes without LLM (free, no API key needed)

• --audit-report <AUDIT_REPORT> — Path to JSON audit report (runs audit if omitted)

• --model <MODEL> — LLM model identifier

• --provider <PROVIDER> — LLM provider: openai, anthropic, custom

  Default value: anthropic

• --max-fixes <MAX_FIXES> — Maximum pages to fix

  Default value: 10

• --profile <PROFILE> — Profile filter: auto (classify), all, content, api

  Default value: auto

  Possible values: auto, all, content, api

• --explain-profile — Print resolved profile + classifier signals to stderr

pageflare geo run

Audit + apply deterministic fixes in one step (equivalent to geo fix --auto). For LLM-driven patches, use geo fix

Usage: pageflare geo run [OPTIONS] [INPUT]

Arguments:

• <INPUT> — Path to the site directory (project root or build output)

  Default value: .

Options:

• -o, --output <OUTPUT> — Output directory. If omitted, uses resolved output dir

• --auto — Run deterministic fixes without LLM (free, no API key needed)

• --audit-report <AUDIT_REPORT> — Path to JSON audit report (runs audit if omitted)

• --model <MODEL> — LLM model identifier

• --provider <PROVIDER> — LLM provider: openai, anthropic, custom

  Default value: anthropic

• --max-fixes <MAX_FIXES> — Maximum pages to fix

  Default value: 10

• --profile <PROFILE> — Profile filter: auto (classify), all, content, api

  Default value: auto

  Possible values: auto, all, content, api

• --explain-profile — Print resolved profile + classifier signals to stderr

pageflare seo

SEO audit and fix tools

Usage: pageflare seo <COMMAND>

Subcommands:

• audit — Run SEO audit on a site
• fix — Generate SEO fixes using LLM (Pro license)

pageflare seo audit

Run SEO audit on a site

Usage: pageflare seo audit [OPTIONS] [INPUT]

Arguments:

• <INPUT> — Path to the site directory (project root or build output)

  Default value: .

Options:

• --url <URL> — Single URL to audit (live fetch, overrides path input)

• --base-url <BASE_URL> — Base URL for path mode (used for site-level checks)

• --format <FORMAT> — Output format: json, table, markdown, github, html, sarif

  Default value: table

• -o, --output <OUTPUT> — Write report to file

• --fail-under <FAIL_UNDER> — Exit with code 2 if score is below this threshold

• --verbose — Show all rules including passed

• --no-save — Skip auto-saving to monitor DB

• --max-pages <MAX_PAGES> — Cap the number of pages scanned (path mode). Useful on large sites to bound audit duration. Pages are taken in scanner order; no flag means scan every HTML file

• --fail-on-finding <FAIL_ON_FINDING> — Exit with code 2 when any finding at or above this severity exists. One of: critical, warning, info. Independent of --fail-under (which gates on score)

  Possible values: critical, warning, info

pageflare seo fix

Generate SEO fixes using LLM (Pro license)

Usage: pageflare seo fix [OPTIONS] [INPUT]

Arguments:

• <INPUT> — Path to the site directory (project root or build output)

  Default value: .

Options:

• -o, --output <OUTPUT> — Output directory. If omitted, uses resolved output dir

• --audit-report <AUDIT_REPORT> — Path to audit report JSON (runs audit if omitted)

• --max-fixes <MAX_FIXES> — Maximum pages to fix

  Default value: 10

• --provider <PROVIDER> — LLM provider (e.g., anthropic, openai, groq)

  Default value: anthropic

• --model <MODEL> — LLM model identifier

  Default value: claude-sonnet-4-6

• --auto — Generate deterministic fixes without LLM (free, no API key needed)

pageflare sites

Manage monitored sites

Usage: pageflare sites <COMMAND>

Subcommands:

• add — Register a site for monitoring
• list — List monitored sites
• remove — Remove a monitored site
• prune — Remove old scan data
• set — Set site configuration
• pages — Manage tracked pages for a site

pageflare sites add

Register a site for monitoring

Usage: pageflare sites add [OPTIONS] <URL>

Arguments:

• <URL> — URL of the site to monitor

Options:

• --name <NAME> — Human-readable name for the site

pageflare sites list

List monitored sites

Usage: pageflare sites list

pageflare sites remove

Remove a monitored site

Usage: pageflare sites remove <ID>

Arguments:

• <ID> — Site ID to remove

pageflare sites prune

Remove old scan data

Usage: pageflare sites prune --older-than <OLDER_THAN>

Options:

• --older-than <OLDER_THAN> — Remove scans older than this duration (e.g., "90d", "30d")

pageflare sites set

Set site configuration

Usage: pageflare sites set [OPTIONS] <URL>

Arguments:

• <URL> — Site URL

Options:

• --psi-api-key <PSI_API_KEY> — Google PageSpeed Insights API key for this site

pageflare sites pages

Manage tracked pages for a site

Usage: pageflare sites pages <COMMAND>

Subcommands:

• list — List tracked pages
• label — Set a label for a page
• exclude — Toggle page exclusion

pageflare sites pages list

List tracked pages

Usage: pageflare sites pages list <URL>

Arguments:

• <URL> — Site URL

pageflare sites pages label

Set a label for a page

Usage: pageflare sites pages label <URL> <PATH> <LABEL>

Arguments:

• <URL> — Site URL
• <PATH> — Page path (e.g. /blog/post)
• <LABEL> — Label to assign to the page

pageflare sites pages exclude

Toggle page exclusion

Usage: pageflare sites pages exclude [OPTIONS] <URL> <PATH>

Arguments:

• <URL> — Site URL
• <PATH> — Page path

Options:

• --exclude — Force-exclude the page (idempotent for scripted use)
• --include — Force-include the page (idempotent for scripted use)

pageflare schedule

Manage scan schedules

Usage: pageflare schedule <COMMAND>

Subcommands:

• add — Add a scan schedule
• list — List scan schedules
• remove — Remove a scan schedule
• pause — Pause a schedule (mark disabled in DB and remove from OS crontab)
• resume — Resume a paused schedule (mark enabled in DB and re-add to crontab)

pageflare schedule add

Add a scan schedule

Usage: pageflare schedule add [OPTIONS] --site <SITE>

Options:

• --site <SITE> — Site URL or ID to schedule

• --every <EVERY> — Scan interval shorthand (e.g., "1h", "6h", "24h")

• --cron <CRON> — Custom cron expression

• --types <TYPES> — Scan types to run (comma-separated: psi,seo,geo). Default: all

  Default value: seo,geo

pageflare schedule list

List scan schedules

Usage: pageflare schedule list

pageflare schedule remove

Remove a scan schedule

Usage: pageflare schedule remove <ID>

Arguments:

• <ID> — Schedule ID to remove

pageflare schedule pause

Pause a schedule (mark disabled in DB and remove from OS crontab)

Usage: pageflare schedule pause <ID>

Arguments:

• <ID> — Schedule ID

pageflare schedule resume

Resume a paused schedule (mark enabled in DB and re-add to crontab)

Usage: pageflare schedule resume <ID>

Arguments:

• <ID> — Schedule ID

pageflare studio

Launch Pageflare Studio dashboard

Usage: pageflare studio [OPTIONS]

Options:

• --port <PORT> — Port to serve on

  Default value: 9876

pageflare speed

Measure page speed via Google PageSpeed Insights

Usage: pageflare speed [OPTIONS] <URL>

Arguments:

• <URL> — URL to test

Options:

• --strategy <STRATEGY> — Strategy: mobile or desktop

  Default value: mobile

• --format <FORMAT> — Output format: table or json

  Default value: table

• --fail-under <FAIL_UNDER> — Exit with code 2 if Lighthouse performance score is below this threshold (0-100). Useful for CI gating

• --no-save — Skip auto-saving the result to the monitor DB

pageflare pwa

PWA configuration and management

Usage: pageflare pwa <COMMAND>

Subcommands:

• init — Scaffold pageflare.pwa.jsonc and generate all PWA assets (icons, manifest, SW, SDK)
• build — Generate / rebuild all PWA assets from pageflare.pwa.jsonc
• config — Cloud-mode: display or update PWA config via API
• disable — Cloud-mode: disable PWA for site via API
• push — Cloud-mode: push notification commands
• stats — Cloud-mode: show PWA analytics summary (last 30 days)

pageflare pwa init

Scaffold pageflare.pwa.jsonc and generate all PWA assets (icons, manifest, SW, SDK)

Usage: pageflare pwa init

pageflare pwa build

Generate / rebuild all PWA assets from pageflare.pwa.jsonc

Usage: pageflare pwa build [OPTIONS]

Options:

• -c, --config <CONFIG> — Path to config file (default: pageflare.pwa.jsonc)
• -f, --force — Force rebuild even if nothing changed

pageflare pwa config

Cloud-mode: display or update PWA config via API

Usage: pageflare pwa config [COMMAND]

Subcommands:

• set — Set a config field

pageflare pwa config set

Set a config field

Usage: pageflare pwa config set <KEY> <VALUE>

Arguments:

• <KEY> — Config key
• <VALUE> — Config value

pageflare pwa disable

Cloud-mode: disable PWA for site via API

Usage: pageflare pwa disable

pageflare pwa push

Cloud-mode: push notification commands

Usage: pageflare pwa push <COMMAND>

Subcommands:

• send — Send a push notification to all subscribers
• list — List push messages and subscriber count

pageflare pwa push send

Send a push notification to all subscribers

Usage: pageflare pwa push send [OPTIONS] <TITLE> <BODY>

Arguments:

• <TITLE> — Notification title
• <BODY> — Notification body text

Options:

• --url <URL> — Optional URL to open on click

pageflare pwa push list

List push messages and subscriber count

Usage: pageflare pwa push list

pageflare pwa stats

Cloud-mode: show PWA analytics summary (last 30 days)

Usage: pageflare pwa stats

pageflare deploy

Optimize and deploy to platform (vercel, netlify, cloudflare-pages)

Usage: pageflare deploy [OPTIONS] [INPUT]

Arguments:

• <INPUT> — Path to the SSG output directory [default: .]

  Default value: .

Options:

• --platform <PLATFORM> — Deployment platform (auto-detected from project files if omitted)

• --prod — Production build (enables platform CDN image rewrites)

• --with-geo <WITH_GEO> — Run GEO optimizations (sitemap, llms.txt, etc.) [default: true]. Pass --with-geo=false to opt out

  Default value: true

  Possible values: true, false

• --with-seo <WITH_SEO> — Run SEO HTML injections [default: true]. Pass --with-seo=false to opt out

  Default value: true

  Possible values: true, false

• --force — Force reprocess even if no files changed

• -c, --config <CONFIG> — Path to config file

Pageflare auto-detects your SSG framework (Next.js, Astro, Gatsby, Nuxt, Vite, Hugo, Jekyll, and more) and resolves the correct build output directory.

Documentation

• Getting Started — install, configure, and run your first optimization
• CLI Commands — full reference for all subcommands and flags
• Configuration — pageflare.jsonc options and per-feature settings
• Changelog — release notes and version history
• WordPress Guide — static export and edge optimization workflows
• Free Audit — live PageSpeed analysis with fix recommendations

Supported Platforms

This package installs a platform-specific binary via optional dependencies:

| Platform | Package | |---|---| | Linux x64 (glibc) | @pageflare/cli-linux-x64 | | Linux arm64 (glibc) | @pageflare/cli-linux-arm64 | | Linux x64 (musl) | @pageflare/cli-linux-x64-musl | | Linux arm64 (musl) | @pageflare/cli-linux-arm64-musl | | Windows x64 | @pageflare/cli-win32-x64 |

macOS support is planned but not yet shipped. macOS users can run pageflare via Docker (docker run --rm -v $(pwd):/site pageflare/cli /site) or via WSL/a Linux VM in the meantime.

Alternative Install Methods

# Homebrew
brew tap getappz/tap && brew install pageflare

# Shell (Linux/macOS)
curl -fsSL https://get.appz.dev/pageflare/install.sh | sh

# PowerShell (Windows)
irm https://get.appz.dev/pageflare/install.ps1 | iex

# Docker
docker run --rm -v $(pwd):/site pageflare/cli /site

License

MIT