CLI Commands

The pageflare binary processes a static site output directory and writes optimized files to the specified output location.

Synopsis

pageflare [INPUT] [OPTIONS]
pageflare optimize [INPUT] [OPTIONS]
pageflare audit [INPUT] [OPTIONS]
pageflare geo audit [INPUT] [OPTIONS]
pageflare geo fix [INPUT] [OPTIONS]
pageflare seo audit [INPUT] [OPTIONS]
pageflare seo fix [INPUT] [OPTIONS]
pageflare pwa build [OPTIONS]
pageflare pwa init
pageflare pwa config [set <KEY> <VALUE>]
pageflare pwa push send <TITLE> <BODY> [--url <URL>]
pageflare pwa push list
pageflare pwa stats
pageflare speed <URL> [OPTIONS]
pageflare sites add|list|remove|prune [OPTIONS]
pageflare schedule add|list|remove [OPTIONS]
pageflare studio [--port <N>]
pageflare init [DIR]
pageflare login
pageflare logout
pageflare status
pageflare upgrade [OPTIONS]

INPUT defaults to . (the current directory) if omitted. If no subcommand is given, optimize is assumed.

Positional Arguments

`INPUT`

Path to the project root or SSG build output directory.

pageflare dist/
pageflare _site/
pageflare public/

pageflare auto-detects your SSG framework (Next.js, Astro, Gatsby, Nuxt, Vite, Hugo, Jekyll, and more) and resolves the correct build output directory. You can point it at either the project root or the build output — it will figure out which is which.

Defaults to . when not specified.

Options

`-o`, `--output <DIR>`

Output directory for optimized files. When omitted, pageflare writes to <project-root>/.appz/output/static.

# Write optimized files to dist/ (update in place)
pageflare dist/ --output dist/

# Write to a separate directory
pageflare dist/ --output optimized/

If you want to overwrite the input directory without specifying --output, use --in-place instead.

`--in-place`

Overwrite files in the input directory instead of writing to a separate output directory.

pageflare dist/ --in-place

This is a convenience flag equivalent to --output <input>. It avoids having to type the same path twice.

`--json`

Output the processing manifest as JSON instead of the default human-readable summary table.

pageflare dist/ --json

Useful for parsing results in scripts or CI pipelines. The JSON output includes per-file details and aggregate statistics.

See the CI/CD guide for an example of consuming JSON output in a pipeline.

`--force`

Force reprocessing of all files even if no files have changed since the last run.

pageflare dist/ --force

By default, pageflare skips files that have not changed (based on content hashing). Use --force when you need a clean rebuild — for example, after updating the pageflare binary or changing config options that affect previously processed files.

`-c`, `--config <PATH>`

Path to the configuration file. Defaults to <input>/pageflare.jsonc.

pageflare dist/ --config ./config/pageflare.jsonc

The config file uses JSONC format (JSON with comments). See the Configuration reference for all available options.

`--platform <PLATFORM>`

Set the deployment platform for platform-specific image optimization. Accepts: auto, vercel, netlify, cloudflare-pages, none.

Default: auto

# Auto-detect from project files (vercel.json, netlify.toml, etc.)
pageflare dist/

# Explicitly set Netlify
pageflare dist/ --platform netlify

# Disable platform-specific optimization
pageflare dist/ --platform none

When set to auto, pageflare detects the platform from config files in your project root. Use an explicit value to override detection or when deploying to a platform without a local config file.

Platform-specific optimization rewrites local image URLs to use the platform’s built-in image resize API (e.g., /_vercel/image or /.netlify/images), enabling automatic format conversion and responsive sizing at the CDN edge.

`--prod`

Enable production-only optimizations. Currently this controls whether Cloudflare Pages image CDN rewrites are applied.

# Local preview — no CDN image rewrites
pageflare dist/

# Production build — enable CDN image rewrites
pageflare dist/ --prod

On Cloudflare Pages, image CDN URLs only work when a custom domain is configured — they are not available on *.pages.dev preview URLs. Without --prod, pageflare skips these rewrites so your local and preview builds work correctly. Any leftover CDN-specific files from a previous --prod run are cleaned up automatically.

For other platforms (Vercel, Netlify), image CDN rewrites are applied regardless of this flag.

`--login`

Log in to activate your Pro license. Opens a browser-based authentication flow and saves a license token to ~/.config/pageflare/license.json.

pageflare --login

After login, Pro features are automatically unlocked in all subsequent runs. See the License Setup guide for details.

`--no-progress`

Disable progress spinners and live output.

pageflare dist/ --no-progress

Progress display is auto-detected: if stdout is not a terminal (i.e., piped or redirected output), spinners are suppressed automatically. Use this flag to force the same behavior in interactive terminals — for example, when writing to a log file.

`--log <LEVEL>`

Set the log verbosity level. Accepts: off, error, warn, info, debug, trace.

Default: warn

# Show informational messages
pageflare dist/ --log info

# Verbose debug output
pageflare dist/ --log debug

# Silence all output
pageflare dist/ --log off

Log messages are written to stderr; the summary table and --json output go to stdout, so they can be separated with standard shell redirection.

`-h`, `--help`

Print the help message and exit.

pageflare --help

`-V`, `--version`

Print the pageflare version and exit.

pageflare --version

Common Usage Examples

Optimize and write back to the same directory

pageflare dist/ --output dist/

Dry run with verbose logging

pageflare dist/ --output /tmp/pf-preview --log info

Generate a config file and then process

pageflare init dist/
# Edit dist/pageflare.jsonc to your needs, then:
pageflare dist/ --output dist/

Force a clean rebuild

pageflare dist/ --output dist/ --force

Use a custom config file path

pageflare dist/ --output dist/ --config ./ci/pageflare.jsonc

Machine-readable output for CI

pageflare dist/ --output dist/ --no-progress --json > pageflare-report.json

Subcommands

`init`

Generate a pageflare.jsonc config file with all options set to their defaults.

pageflare init
pageflare init dist/

The optional argument specifies the directory to write the config file to (defaults to .). Run this once to get a fully-commented config file you can then customize.

`audit`

Run a comprehensive audit of your static site — combines performance checks, SEO scoring (23 rules), and GEO/AI-readiness scoring (37 rules) in a single command.

pageflare audit
pageflare audit dist/
pageflare audit dist/ --json
pageflare audit --fail-under 70

The optional argument specifies the directory to scan (defaults to .).

Output

The audit produces three sections:

Performance — images, CSS, JS, fonts, minification, and other optimization issues.
SEO — score out of 100 with top recommendations (indexability, meta tags, links, i18n, readability, images).
GEO — score out of 100 with AI-readiness findings (discoverability, structured data, content quality, signals).

Options

Flag	Description
`--json`	Output all three reports as a combined JSON object
`--no-report`	Skip HTML report generation
`-o`, `--output <PATH>`	Custom path for the HTML report
`-c`, `--config <PATH>`	Path to config file
`--platform <PLATFORM>`	Deployment platform (auto, vercel, netlify, cloudflare-pages, none)
`--fail-under <SCORE>`	Exit with code 2 if SEO or GEO score falls below this threshold

The HTML report is written to the input directory by default. The JSON output includes performance, seo, and geo keys with the full report for each engine.

`geo audit`

Audit a website for AI-readiness (Generative Engine Optimization). Scores pages 0–100 across 8 categories — discoverability, structured data, content quality, technical, signals, AI discovery, brand & entity, and negative signals — and assigns an A–F grade.

# Audit a local build directory
pageflare geo audit dist/

# Audit with a base URL for site-level checks (robots.txt, llms.txt, sitemap)
pageflare geo audit dist/ --base-url https://example.com

# Audit a live URL (includes response time and content-type analysis)
pageflare geo audit --url https://example.com

# GitHub Markdown output for PR comments
pageflare geo audit dist/ --format github

# HTML report with dark/light mode
pageflare geo audit dist/ --format html --output geo-report.html

# SARIF output for GitHub Code Scanning
pageflare geo audit dist/ --format sarif --output results.sarif

# JSON output for CI pipelines
pageflare geo audit dist/ --format json --output geo-report.json

# Generate badge snippets for your README
pageflare geo audit dist/ --badge

# Fail the build if score is below a threshold
pageflare geo audit dist/ --fail-under 70

The positional INPUT argument defaults to . (the current directory). pageflare auto-detects your framework and resolves the correct build output directory — same as the optimize command. If a prior optimize run has already written output (e.g. to .appz/output/static/), geo audit reads from there automatically.

Options

Flag	Description
`--url <URL>`	Single URL to audit (fetches live, overrides path input)
`--base-url <URL>`	Base URL for site-level checks in path mode
`--max-pages <N>`	Limit number of pages to audit
`--format <FORMAT>`	Output format: `json`, `table`, `markdown`, `github`, `html`, `sarif` (default: `table`)
`-o`, `--output <FILE>`	Write report to file instead of stdout
`--fail-under <N>`	Exit code 2 if score is below this threshold
`--badge`	Output badge snippets (Markdown, HTML) after the audit
`--verbose`	Show all rules including passed ones

Exit Codes

Code	Meaning
`0`	Audit completed successfully
`1`	Error (network failure, invalid input, etc.)
`2`	Score below `--fail-under` threshold

`geo fix`

Fix GEO issues found by geo audit. Requires a paid CLI license (Solo or higher). Both modes — --auto for deterministic fixes and the default LLM mode — are gated to paid tiers. The LLM mode accepts your own OpenAI / Anthropic / Gemini key (BYOK); the deterministic --auto mode needs no API key.

# Auto-fix: generate robots.txt, llms.txt, schemas, and meta tags (free)
pageflare geo fix dist/ --auto

# Write fixes to a custom output directory
pageflare geo fix dist/ -o fixed/

# Fix issues using an existing audit report
pageflare geo fix dist/ --audit-report geo-report.json

# Run audit and fix in one step (runs audit first if no report provided)
pageflare geo fix dist/

The positional INPUT argument works the same as optimize — auto-detects your framework and resolves the build output directory. Fixes are written to the resolved output directory (e.g. .appz/output/static/) by default. If optimize has already run, geo fix reads from and writes to the same output directory, making the commands composable and idempotent.

Options

Flag	Description
`-o`, `--output <DIR>`	Output directory for fixed files (defaults to resolved output dir)
`--auto`	Run deterministic fixes without LLM (no API key needed; still requires Solo+ license)
`--audit-report <FILE>`	JSON report from `geo audit` (runs audit if omitted)
`--model <MODEL>`	LLM model identifier
`--provider <NAME>`	LLM provider: `openai`, `anthropic`, `custom` (default: `anthropic`)
`--max-fixes <N>`	Maximum pages to fix (default: 10)

`seo audit`

Audit a website for technical SEO issues. Scores pages 0–100 across four categories — indexability, meta & structure, link architecture, and i18n & media — and assigns an A–F grade.

# Audit a local build directory
pageflare seo audit dist/

# Audit with a base URL for absolute URL resolution
pageflare seo audit dist/ --base-url https://example.com

# Audit a live URL
pageflare seo audit --url https://example.com

# JSON output for CI pipelines
pageflare seo audit dist/ --format json --output seo-report.json

# Fail the build if score is below a threshold
pageflare seo audit dist/ --fail-under 70

# Show all rules including passed ones
pageflare seo audit dist/ --verbose

The positional INPUT argument defaults to . (the current directory). Like optimize and geo audit, it auto-detects your framework and reads from a prior optimize output if one exists.

Options

Flag	Description
`--url <URL>`	Single URL to audit (live fetch, overrides path input)
`--base-url <URL>`	Base URL for site-level checks in path mode
`--format <FORMAT>`	Output format: `json`, `table` (default: `table`)
`-o`, `--output <FILE>`	Write report to file instead of stdout
`--fail-under <N>`	Exit code 2 if score is below this threshold
`--verbose`	Show all rules including passed ones

Exit Codes

Code	Meaning
`0`	Audit completed successfully
`2`	Score below `--fail-under` threshold

`seo fix`

Generate targeted patches for SEO issues found by seo audit. Requires a paid CLI license (Solo or higher). Both the --auto deterministic mode and the default LLM mode are gated to paid tiers — LLM mode uses your own API key (BYOK); --auto needs no key.

# Fix issues using an existing audit report
pageflare seo fix dist/ --audit-report seo-report.json

# Fix without a report (runs audit automatically)
pageflare seo fix dist/

# Write fixes to a custom output directory
pageflare seo fix dist/ -o fixed/

# Audit + fix in one step
pageflare seo run dist/

The positional INPUT argument works the same as optimize — fixes are written to the resolved output directory by default, making seo fix composable with optimize and idempotent on repeated runs.

Options

Flag	Description
`-o`, `--output <DIR>`	Output directory for fixed files (defaults to resolved output dir)
`--audit-report <FILE>`	JSON report from `seo audit` (runs audit if omitted)
`--max-fixes <N>`	Maximum pages to fix (default: 10)
`--provider <NAME>`	LLM provider: `anthropic`, `openai`, `groq` (default: `anthropic`)
`--model <MODEL>`	LLM model identifier (default: `claude-sonnet-4-6`)

`upgrade`

Update pageflare to the latest version. The CLI detects how it was installed and either self-replaces the binary or tells you the correct package-manager command.

pageflare upgrade

If installed via the official install script (~/.pageflare/bin), the binary is downloaded and replaced in-place. For npm and Homebrew installs, the command prints the appropriate upgrade instruction instead.

`--force`

Force reinstall of the current version even if already up to date.

pageflare upgrade --force

Auto update notifications

After each optimize run, pageflare checks for a newer version in the background (cached for 12 hours). If an update is available, a one-line notice is printed after the summary. Set PAGEFLARE_TELEMETRY=false to disable the check.

`speed`

Measure real-world page performance via Google PageSpeed Insights. Returns both Lighthouse lab metrics and Chrome User Experience Report (CrUX) field data when available.

pageflare speed https://example.com
pageflare speed https://example.com --strategy desktop
pageflare speed https://example.com --format json

Options

Flag	Description
`--strategy <STRATEGY>`	Device profile: `mobile` (default) or `desktop`
`--format <FORMAT>`	Output format: `table` (default) or `json`

Metrics

Metric	Source	Description
LCP	Lab + Field	Largest Contentful Paint — when the main content is visible
FCP	Lab + Field	First Contentful Paint — when the first content appears
TBT	Lab	Total Blocking Time — time the main thread is blocked
CLS	Lab + Field	Cumulative Layout Shift — visual stability score
SI	Lab	Speed Index — how quickly content is visually populated
INP	Field	Interaction to Next Paint — input responsiveness

Field data uses the 75th percentile (p75) from real Chrome users over the last 28 days. Not all sites have field data — it requires sufficient traffic in the Chrome User Experience Report.

API Key

Works without an API key but with lower rate limits. For regular use, set a Google API key:

export GOOGLE_API_KEY=your_key_here
pageflare speed https://example.com

Create a key at Google Cloud Console with the PageSpeed Insights API enabled.

`sites`

Manage sites registered for monitoring. Sites are stored in a local SQLite database at ~/.pageflare/monitor.db and drive scheduled scans, alerts, and the Studio dashboard.

pageflare sites add https://example.com --name "My Site"
pageflare sites list
pageflare sites remove 3
pageflare sites prune --older-than 90d

Subcommands

Subcommand	Description
`add <URL>`	Register a new site. Use `--name` to set a display name.
`list`	Show all registered sites with their IDs.
`remove <ID>`	Unregister a site by ID.
`prune --older-than <DURATION>`	Delete scan history older than the given duration (e.g. `30d`, `90d`). The site registration itself is kept.

Pair sites with schedule to run recurring scans, and studio to view results.

`schedule`

Register recurring scans for monitored sites. Schedules are written to the OS crontab and trigger pageflare speed, seo audit, or geo audit runs at the configured interval. Results auto-save to the monitor DB and feed the Studio dashboard and alert channels.

pageflare schedule add --site https://example.com --every 6h --types speed,seo
pageflare schedule add --site 1 --cron "0 */4 * * *" --types geo
pageflare schedule list
pageflare schedule remove 2

Subcommands

Subcommand	Description
`add`	Create a schedule. Requires `--site` and exactly one of `--every` or `--cron`.
`list`	Show all schedules with cron expression, scan types, and enabled status.
`remove <ID>`	Delete a schedule by ID (also removes the crontab entry).

Options (`add`)

Flag	Description
`--site <URL_OR_ID>`	Site URL or numeric ID from `pageflare sites list`. Must be registered first.
`--every <INTERVAL>`	Shorthand interval: `1h`, `6h`, `24h`. Max 24h. Mutually exclusive with `--cron`.
`--cron <EXPR>`	Standard 5-field cron expression (e.g. `"0 /4 * *"`). Mutually exclusive with `--every`.
`--types <LIST>`	Comma-separated scan types: `speed`, `seo`, `geo`.

Schedules survive reboots via the system crontab.

`studio`

Launch pageflare Studio — a local web dashboard showing monitored site trends, scan history, alerts, and per-page SEO findings. Studio ships as a separate binary that must be installed alongside the CLI.

pageflare studio
pageflare studio --port 8080

Open http://localhost:9876 (default port) in your browser.

Options

Flag	Description
`--port <PORT>`	Port to serve on. Default: `9876`.

If pageflare-studio isn’t on your PATH, install it with cargo install pageflare-studio.

Exit Codes

Code	Meaning
`0`	Success — all files processed without errors
`1`	One or more files encountered errors during processing
`2`	GEO or SEO audit score below `--fail-under` threshold

CLI Commands

Synopsis

Positional Arguments

INPUT

Options

-o, --output <DIR>

--in-place

--json

--force

-c, --config <PATH>

--platform <PLATFORM>

--prod

--login

--no-progress

--log <LEVEL>

-h, --help

-V, --version

Common Usage Examples

Optimize and write back to the same directory

Dry run with verbose logging

Generate a config file and then process

Force a clean rebuild

Use a custom config file path

Machine-readable output for CI

Subcommands

init

audit

Output

Options

geo audit

Options

Exit Codes

geo fix

Options

seo audit

Options

Exit Codes

seo fix

Options

upgrade

--force

Auto update notifications

speed

Options

Metrics

API Key

sites

Subcommands

schedule

Subcommands

Options (add)

studio

Options

Exit Codes

`INPUT`

`-o`, `--output <DIR>`

`--in-place`

`--json`

`--force`

`-c`, `--config <PATH>`

`--platform <PLATFORM>`

`--prod`

`--login`

`--no-progress`

`--log <LEVEL>`

`-h`, `--help`

`-V`, `--version`

`init`

`audit`

`geo audit`

`geo fix`

`seo audit`

`seo fix`

`upgrade`

`--force`

`speed`

`sites`

`schedule`

Options (`add`)

`studio`