@pagepocket/cli

CLI for capturing offline snapshots of web pages using the PagePocket library and plugin-owned HTTP capture.

Install

npm i -g @pagepocket/cli

Usage

pp archive https://example.com
pp archive https://example.com -o ./snapshots
pp archive https://example.com -o ./snapshots --overwrite

Configuration

PagePocket CLI stores a persistent config file under your user config directory:

• Linux: ~/.config/pagepocket/config.json
• Windows: %APPDATA%\\pagepocket\\config.json

Initial config:

{
  "plugins": []
}

Plugins

Manage configured plugins:

pp plugin ls
pp plugin add <plugin-name>
pp plugin set <plugin-name> [...options]
pp plugin update [plugin-name]
pp plugin doctor [plugin-name]
pp plugin remove <plugin-name>
pp plugin uninstall <plugin-name> [--from-config]
pp plugin prune

Options passing:

# no options
pp plugin add @scope/plugin

# object options (becomes { options: { arg1: "xxx" } })
pp plugin add @scope/plugin --option-arg1 xxx --option-arg2 yyy

# array options (becomes { options: ["1", "2"] })
pp plugin add @scope/plugin --option 1 --option 2

Notes:

• pp plugin remove only removes the entry from config.json (it does not uninstall the package).
• pp plugin set updates options for an already configured plugin.
• pp plugin update <plugin-name> reinstalls that plugin to latest.
• pp plugin update reinstalls all configured plugins to latest.
• pp plugin doctor checks plugin install/load health and exits non-zero on failures.
• pp plugin uninstall <plugin-name> removes the installed package; add --from-config to also remove config.
• pp plugin prune removes installed packages that are no longer referenced in config.json.
• During pp archive ..., the CLI reads config.json and tries to load all configured plugins. If a plugin fails to load, it will be skipped and the archive will continue.

Plugin packages are installed to your user data directory (not the config directory):

• Linux: ~/.local/share/pagepocket/plugins/
• macOS: ~/Library/Application Support/pagepocket/plugins/
• Windows: %APPDATA%\\pagepocket\\plugins\\

Output

Snapshots are written to a folder named after the page title inside the output directory (default: current directory).

• The title is sanitized for safe filesystem usage.
• If the title is missing/blank, we fall back to the page hostname, then snapshot.
• If the target path already exists and --overwrite is not set, we de-dupe by appending -2, -3, ...

For --emit zip, the output is written as <output>/<title>.zip.

Example layout:

<output>/<title>/index.html
<output>/<title>/api.json
<output>/<title>/<same-origin paths>
<output>/<title>/external_resources/<cross-origin paths>

Development

pnpm install
pnpm --filter @pagepocket/cli build