CLI Commands

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

Synopsis

pageflare [INPUT] [OPTIONS]

INPUT defaults to . (the current directory) if omitted.

Positional Arguments

INPUT

Path to the SSG output directory to process.

pageflare dist/
pageflare _site/
pageflare public/

Defaults to . when not specified, which is useful when running from within your build output directory.

Options

-o, --output <DIR>

Output directory for optimized files. When omitted, pageflare writes to <input>/.appz.

# 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.

---

--init

Generate a pageflare.jsonc config file in the input directory with all options set to their defaults.

pageflare dist/ --init

Run this once to get a fully-commented config file you can then customize. Does not process any files — exits after writing the config.

---

--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 dist/ --init
# 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

Exit Codes

Code	Meaning
0	Success — all files processed without errors
1	One or more files encountered errors during processing