Analytics Audit

A Search Console and GA4 analytics CLI. Point it at a Google property; it pulls time-series, public tags, and (when configured) Chrome field data plus a homepage lab check, and writes one machine-readable JSON file (out/analytics.json by default).

What pend-analytics is

Google setup and traffic evidence, honestly labelled. Search Console, GA4, public tags, and optional CrUX / PageSpeed land in run.analytics. Insights flag period drops and low-CTR queries. Nothing is turned into a ranking or readiness score.

It is a JSON engine, not a report UI. Human-facing reports live in whatever consumes out/analytics.json, which keeps this repo free of presentation decisions.

• Project-local config - one audit-config-analytics.toml holds the property ids, date window, and observe switch.
• Read-only Google APIs - a service account with Restricted / Viewer access. A leaked key cannot change Search Console or GA4.
• Soft-fail providers - auth and API errors land in run.analytics.errors[] and the process still exits 0.
• Observe off by default - Chromium collect intercept is opt-in.

Pair it with pend-seo for technical SEO, and pend-a11y for accessible names, alt text and WCAG.

Documentation

• docs/input.md - every CLI flag and project-config key
• docs/output.md - the --out JSON contract, and how the zeros are read
• docs/analytics.md - Search Console and GA4 setup
• docs/security.md - what this tool connects to and writes
• docs/releasing.md - tag a release and the notes format
• examples/analytics.toml - annotated project config

Repository layout

docs/       input, output, analytics, security, and release notes
examples/   annotated analytics.toml
src/        CLI, config, Google pull, insights, JSON writer, MCP
test/       tests

Getting started

Requires Node.js 22.12+. No browser install unless you opt into observe (see docs).

Requests to websites use a pend-analytics/VERSION user agent so a site owner reading their logs can identify or block us.

Install

As a project dependency, pinned to a release tag:

npm install github:pendulumdev/pend-audit-analytics#v0.3.1

Installing from git compiles dist/ on install via the prepare script, so both the CLI and the ./types export resolve. If you only need the types for a report UI, make it a devDependency - every export is compile-time only. Distribution is git tags and GitHub Releases; npm under @pendulumdev is not scheduled. See ROADMAP.md.

From a clone:

git clone https://github.com/pendulumdev/pend-audit-analytics.git
cd pend-audit-analytics
npm install
npm run build
npm link          # exposes `pend-analytics` on your PATH

Or without linking: npx tsx src/cli.ts --help, or node dist/cli.js --help after a build.

Use in a project

pend-analytics init                 # asks project / URL / GSC / GA4 / credentials / PageSpeed; writes audit-config-analytics.toml
pend-analytics audit                # -> out/analytics.json
pend-analytics audit -o reports/site.json
pend-analytics mcp                  # MCP stdio (Cursor / Claude Desktop)
pend-analytics mcp --http           # Streamable HTTP on 127.0.0.1:3000/mcp

MCP (agents)

Same implementations as the CLI. Tools: docs, config validate, projected analytics_audit_run, run_summarize. Agent instructions are in SKILL.md.

Cursor mcp.json:

{
  "mcpServers": {
    "pend-analytics": {
      "command": "npx",
      "args": ["-y", "github:pendulumdev/pend-audit-analytics", "mcp"]
    }
  }
}

This CLI does not host public HTTP. --http binds loopback by default.

Develop

npm install
npm test
npm run build
npm run dev -- audit -c examples/analytics.toml

The example is covered by tests, so a config key cannot change without the example that documents it failing.

Keep the dependency surface small: commander, TOML, zod, MCP SDK, and google-auth-library. Playwright is optional and only needed for observe. See CONTRIBUTING.md.

Versioning and tags

• Version source of truth: root package.json, which pend-analytics --version reads
• A release is an annotated git tag vX.Y.Z on main
• Consumers should pin the tag, not a branch, and fail closed on a mismatch
• Write docs/releases/vX.Y.Z.md first - the workflow publishes that file as the GitHub Release body. Format and steps: docs/releasing.md

git tag -a v0.3.0 -m "v0.3.0"
git push origin main --tags

Pushing the tag runs the release workflow, which refuses to publish if the tag and package.json disagree - otherwise anyone pinning that tag would get a build that misreports its own version. It then re-runs the full gate against the tagged commit and publishes a GitHub release.

Limits (intentional)

• Does not produce a readiness score
• Does not predict rankings or replace keyword research
• API failures soft-fail into the report rather than failing the run
• Observe (Chromium collect intercept) is off by default
• Needs a Google service account with read access to Search Console and/or GA4
• Named rivals each add a homepage PageSpeed lab (mobile and desktop). More than a few can make the pull last many minutes; each lab call can wait up to 45s before it times out

Contributing

Issues and pull requests are welcome at pendulumdev/pend-audit-analytics. Prefer small, single-purpose changes. Start with CONTRIBUTING.md; report vulnerabilities per SECURITY.md.

Contributors

• Pendulum - lead development and maintenance
• Devhalls - primary author

License

MIT - full text in LICENSE. Third-party notices in NOTICE.

---