Skip to content
Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace
BranchesTags

Latest commit

 

History

26 Commits

Folders and files

NameName
Last commit message
Last commit date
.github/ISSUE_TEMPLATE
.github/ISSUE_TEMPLATE
 
 
bin
bin
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
SECURITY.md
SECURITY.md
 
 
action.yml
action.yml
 
 
package.json
package.json
 
 

Repository files navigation

@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

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

About

Optimize static sites for PageSpeed — HTML, CSS, JS minification, image optimization, font subsetting, critical CSS, and more.

pageflare.dev

Topics

core-web-vitalslighthousepagespeedperformancestatic-site-optimizationweb-performancewordpress

Resources

Readme
MIT license

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages