CLI flags and project config that drive a pend-analytics run.
Input (this page) · Output · Analytics · Security
Flags and arguments on pend-analytics. A flag that also exists in config wins over the TOML key. --out is CLI-only; it is not a TOML key.
| name | value example | description | usage |
|---|---|---|---|
-V, --version | Print the package version and exit. | Root only. Same value as pend-analytics --version. | |
-h, --help | Print help for the program or a command. | Works on the root and every command. | |
init | |||
-c, --config | audit-config-analytics.toml | Config path to write. | Optional. Default is audit-config-analytics.toml. See [Init](#init). |
-f, --force | Overwrite an existing file at that path. | Boolean. Refuses to overwrite without this flag. | |
audit | |||
-c, --config | audit-config-analytics.toml | Project config to load. | Default audit-config-analytics.toml. See [Analytics pull](#analytics-pull). |
-o, --out | out/analytics.json | Path and filename for the analytics JSON. | CLI only. Default out/analytics.json. Parent directories are created. PageSpeed screenshots, when a key is set, go in dirname(--out)/psi-shots/. |
mcp | |||
--http | Serve Streamable HTTP on /mcp instead of stdio. | Boolean. Default is stdio for Cursor / Claude Desktop. | |
--port | 3000 | HTTP port. | Default 3000. Only used with --http. |
--bind | 127.0.0.1 | HTTP bind address. | Default loopback. Do not bind 0.0.0.0 unless you intend to expose a Google-API client on that machine. |
Questions pend-analytics init asks before writing one config file. Multi-choice uses arrow keys or a number; Enter keeps the highlighted default. Text fields show the default in brackets. When it finishes it prints the written path and the sources it stored.
At least one of Search Console or GA4 is required. Skipping both re-asks.
| name | value example | description | usage |
|---|---|---|---|
Project name | Analytics audit | Label copied onto the config. | Text. Default Analytics audit. |
URL | https://example.com | Written as baseUrl. | Required text. Must be http:// or https://. No default. Used for the public tag scan, CrUX origin, and homepage PageSpeed lab check. |
Search Console | Yes | Whether to write a Search Console source. | Multi-choice: Yes, Skip. Default Yes. |
Search Console property | sc-domain:example.com | Written as analytics.searchConsole.siteUrl. | Required when Search Console is Yes. Hidden when Skip. Domain property (sc-domain:example.com) or URL-prefix with a trailing /. |
GA4 | Yes | Whether to write a GA4 source. | Multi-choice: Yes, Skip. Default Yes. |
GA4 property id | 123456789 | Written as analytics.ga4.propertyId. | Required when GA4 is Yes. Hidden when Skip. Numeric. A properties/ prefix is stripped. |
Service account JSON | ~/Secrets/analytics-sa.json | Written as analytics.credentialsPath. | Optional text. Enter skips and leaves GOOGLE_APPLICATION_CREDENTIALS as the source. Must be a local .json path, not a URL. |
PageSpeed API key | AIza... | Written as analytics.pagespeedApiKey. | Optional text. Enter skips and leaves PAGESPEED_API_KEY as the source. Must be the key string, not a URL. Setup: [analytics.md](analytics.md#4-pagespeed-api-key-optional). |
Keys in examples/analytics.toml for pend-analytics audit. pend-analytics init writes one starter file (audit-config-analytics.toml) from the answers above.
There are no targets, viewports, sitemap, or failOn keys. This engine does not crawl pages and does not score readiness.
At least one of [analytics.searchConsole] or [analytics.ga4] is required. pend-analytics audit force-enables the configured sources even when enabled = false.
Top-level rangeDays, comparePrevious, credentialsPath, pagespeedApiKey, searchConsole, and ga4 fold into [analytics] when the nested key is unset.
A leftover outDir key is rejected. Pass --out instead.
Credentials, scopes, per-property access and troubleshooting are their own subject - see analytics.md.
| name | value example | description | usage |
|---|---|---|---|
project | "Example Project" | Label copied onto the analytics JSON. | Required. |
standard | "Pendulum_Analytics_v1" | Engine id stored on the run. | Required. Only this value is written. Legacy Pendulum_SEO_v1 is still accepted and normalised. |
baseUrl | "https://example.com" | Site origin for the public HTML tag scan, CrUX origin, and homepage PageSpeed lab check. | Optional. Omit and those public probes are skipped. |
analytics | |||
enabled | true | Ignored by audit (force-enabled). | Rejected if true with no sources. |
credentialsPath | "" | Path to a service-account JSON. | Optional. Empty or omit uses GOOGLE_APPLICATION_CREDENTIALS. |
pagespeedApiKey | "" | PageSpeed Insights and CrUX API key. | Optional. Empty or omit uses PAGESPEED_API_KEY. The environment wins when both are set. Do not commit the key. |
rangeDays | 28 | Inclusive day count for the primary window. | Default 28. Max 90. |
startDate / endDate | "2026-01-01" | YYYY-MM-DD overrides. | Must be set together. When both set, rangeDays is ignored. |
comparePrevious | true | Compare against the immediately preceding window of equal length. | Default true. |
observeEvents | false | Optional Chromium collect intercept. | Default false. Also ANALYTICS_OBSERVE=1 (SEO_ANALYTICS_OBSERVE still accepted). |
rivals | ["https://rival.example"] | Named rival https origins. | Optional. Homepage CrUX and PageSpeed lab, same key as the site. Never a Google property of yours. |
searchConsole.siteUrl | "sc-domain:example.com" | Search Console property. | Domain property or a URL-prefix with a trailing /. |
ga4.propertyId | "123456789" | Numeric GA4 property id. | A properties/ prefix is stripped. |