Marketing

Google Analytics 4

google-analytics-pp-cli

Agent-first Google Analytics 4 CLI with typed Data/Admin/Funnel API coverage and one-call reports for channels, pages, funnels, anomalies, revenue, and health.

Printed by @cathrynlavery (Cathryn Lavery)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install google-analytics

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-google-analytics --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-google-analytics skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-google-analytics. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

View source on GitHub →

google-analytics-pp-cli is an agent-first GA4 CLI for live analytics work. It covers the GA4 Data API, the GA4 Admin API discovery calls, and curated novel commands that answer the questions agents actually ask without stitching multiple raw API calls together.

Created by @cathrynlavery (Cathryn Lavery). Contributors: @cathrynlavery (Cathryn Lavery).

Install / build

PP_LIBRARY_REPO=/path/to/printing-press-library pp-sync build google-analytics-pp-cli

Auth

Use a service-account JSON key with Analytics readonly scope. Set GOOGLE_APPLICATION_CREDENTIALS to your service-account JSON path, or pass --credentials explicitly.

Save several service-account keys once, then select one without another login:

google-analytics-pp-cli auth add bestself --from-credentials /path/to/bestself.json
google-analytics-pp-cli auth add littlemight --from-credentials /path/to/littlemight.json
google-analytics-pp-cli auth accounts
google-analytics-pp-cli auth set-default bestself
google-analytics-pp-cli channels --account littlemight --property PROPERTY_ID --agent
google-analytics-pp-cli auth remove littlemight --yes

auth login is an alias for auth add: it imports a service-account key, with no browser consent. Keys are copied to ~/.config/google-analytics-pp-cli/<name>/credentials.json with mode 0600. Each command automatically mints a fresh access token from the selected key; tokens are never displayed or saved. Accounts must have Viewer access to the relevant GA4 properties. Names use 1–63 lowercase letters, digits, dots, underscores or hyphens, starting with a letter or digit; consecutive dots are rejected. Existing accounts are never overwritten; switch defaults before removing the current named default. Removal deletes the saved copy only and does not revoke the key at Google.

Selection: --account, GOOGLE_ANALYTICS_ACCOUNT, saved default, then legacy default. Named accounts ignore GOOGLE_APPLICATION_CREDENTIALS. Without a named selection, --credentials still overrides GOOGLE_APPLICATION_CREDENTIALS; an explicit credential path bypasses the saved default and conflicts with account selectors. The reserved default account keeps existing external credential-path usage unchanged; it has no implicit local fallback. Use auth set-default default to return to that behavior. doctor and agent-context report the active name without exposing keys or tokens.

GA4 property resolution for data commands: --property, then GA4_PROPERTY_ID. The CLI does not hard-code the first authorized property or the second authorized property property IDs. For fleet health checks, pass explicit properties or set GA4_PROPERTY_IDS.

Important gotcha: Google Cloud API access is not GA4 property access. The service account must also be granted Viewer access inside each GA4 property. health / doctor distinguishes invalid credentials from property not shared / permission denied.

Global agent flags

Every command inherits:

--agent = --json --compact --no-input --yes
--json
--compact
--no-input
--yes
--property
--credentials
--timeout

Raw API wrappers

report — GA4 Data API runReport (--metrics, --dimensions, --start, --end, --filter, --order, --limit)
pivot — runPivotReport
batch — batchRunReports
realtime — runRealtimeReport
metadata — list valid dimensions/metrics for a property
compatibility — checkCompatibility
properties — Admin API accountSummaries.list
property — Admin API properties.get
streams — Admin API properties.dataStreams.list

Novel commands

channels — sessions/users/conversions/revenue by default channel group.
sources — source/medium acquisition breakdown with computed conversion rate.
top-pages — landing pages by sessions, engagement, conversions, revenue.
events / conversions — events or conversions over time with trend summary.
funnel — v1alpha runFunnelReport for a named event sequence.
compare — period-over-period metric deltas and percent changes.
whats-changed — anomaly-style mover scan across key dimensions.
revenue — ecommerce revenue, AOV, transactions by channel/source.
audience / cohort — cheap audience and retention snapshots.
health / doctor — token mint, Admin visibility, and per-property access grants.

Examples

google-analytics-pp-cli agent-context --agent
google-analytics-pp-cli health --properties "$GA4_PROPERTY_IDS" --agent
google-analytics-pp-cli channels --property "$GA4_PROPERTY_ID" --start 28daysAgo --end yesterday --agent
google-analytics-pp-cli compare --property "$GA4_PROPERTY_ID" --metric sessions,totalRevenue --period wow --agent
google-analytics-pp-cli whats-changed --property "$GA4_PROPERTY_ID" --agent
google-analytics-pp-cli funnel --property "$GA4_PROPERTY_ID" --steps view_item,add_to_cart,begin_checkout,purchase --agent