puremetrix

puremetrix

Add PureMetrix cookieless, privacy-first analytics to your project with one command:

npx puremetrix@latest init

The CLI detects your framework, signs you in through the browser (no password in the terminal), picks or creates the website and adds the tracking code. It shows a diff before writing, never adds a second snippet when you run it again, and npx puremetrix@latest remove restores your files.

Prefer an npm dependency with typed init() / track()? That is @puremetrix/tracker — npx puremetrix@latest init --mode package installs and wires it up for you.

Docs · Deutsch · Dashboard · @puremetrix/tracker

What it does

◆ PureMetrix · installation
◇ Project detected: Next.js (App Router) · pnpm
◇ Signing in – your browser will open …
│ Code: WDJB-MJHT   (https://app.puremetrix.org/cli)
✔ Signed in as you@example.com
? Which website?  1) example.com  2) Add a new website …
◇ Changes:
│ app/layout.tsx  +6 −0
✔ Done. Changed: app/layout.tsx
◇ Waiting for the first pageview from example.com … (Ctrl+C to skip)
✔ First pageview from example.com arrived.

With --mode package the CLI installs @puremetrix/tracker ^0.3.0 instead: init() in the entry file (Vite, CRA, Vue CLI) or the PureMetrixProvider from @puremetrix/tracker/next (Next.js: app/layout.tsx, or pages/_app.tsx, created if missing). Running it again on a setup from CLI 0.1 switches the import to /next and upgrades the package. | Vite (React/Vue/Svelte/Solid), CRA, Vue CLI, Angular | index.html | | Astro | layout with </head> (is:inline) | | SvelteKit | src/app.html | | Nuxt | nuxt.config.ts → app.head.script | | Remix / React Router, TanStack Start | app/root.tsx / __root.tsx | | Gatsby | gatsby-ssr.js | | Laravel (Blade) | resources/views/layouts/*.blade.php | | Ruby on Rails | app/views/layouts/application.html.erb (HAML/Slim → manual hint) | | Django | base template, e.g. templates/base.html | | Hugo | your own layouts/_default/baseof.html (theme files → manual hint) | | Jekyll | _includes/head.html / _layouts (theme gem → manual hint) | | Eleventy | base layout in _includes/ | | Plain HTML, Shopify theme | chosen .html files / layout/theme.liquid | | WordPress | points you to the plugin |

The snippet is async with a tiny queue stub, so window.puremetrix("Signup") never throws before the script has loaded.

Commands

Options: --key pk_… --domain example.com (no sign-in) · --site <id|domain> · --mode script|package · --framework <id> · --cwd <dir> · --dry-run · --diff · -y/--yes · --json · --no-verify · --timeout <s> · --no-browser · --skip-install · --lang en|de

Environment: PUREMETRIX_TOKEN (CI / agents), PUREMETRIX_API_URL, PUREMETRIX_LANG, NO_COLOR, PUREMETRIX_NO_UPDATE_CHECK.

Exit codes: 0 ok · 1 error / manual step needed · 2 usage · 3 verify timed out.

CI and AI agents

npx puremetrix@latest init --yes --key pk_… --domain example.com      # no account access needed
PUREMETRIX_TOKEN=pxc_… npx puremetrix@latest init --yes --json --site example.com

• Create CI tokens (name, scopes, 7–365 days, shown once) under Settings → Connected apps.
• Without a TTY, or with --yes / --json, the CLI never waits for a browser: no token → exit 2, error_code: "login_required".
• Two-step sign-in for agents: npx puremetrix@latest login --json prints { verification_url, user_code, expires_in, next_step } and exits; after you approve, npx puremetrix@latest login --complete stores the token.
• --json failures: { "ok": false, "error_code": "…", "message": "…" }. Codes: login_required, login_not_started, login_denied, login_expired, token_invalid, insufficient_scope, network_error, timeout, api_error, site_limit, site_taken, site_not_found, site_required, invalid_domain, invalid_key, invalid_option, monorepo_ambiguous, manual_install, verify_timeout, aborted, not_logged_in, unknown_command. See the docs and the ready-to-paste agent prompt.
• Requests time out after 15 s; transient network errors and 5xx/429 are retried with backoff.
• Update notice: at most one anonymous GET to registry.npmjs.org per day, only in an interactive terminal. No telemetry.

Security

• Device-code sign-in: you approve a short code in the browser; the CLI never sees your password.
• The token (pxc_…) can only list websites, add websites and read install status — never delete websites or touch team, API keys or billing. It expires after 90 days without use.
• Stored only on your machine: ~/.config/puremetrix/credentials.json (mode 0600), on Windows %APPDATA%\puremetrix\credentials.json.
• The approval page shows the requesting IP (and approximate country where available) – deny anything you did not start.
• Revoke devices and CI tokens any time under Settings → Connected apps.
• Only the public site key (pk_…) is written into your code.
• Zero runtime dependencies.

Deutsch

npx puremetrix@latest init

Die CLI erkennt Ihr Framework, meldet Sie über den Browser an (kein Passwort im Terminal), wählt die Website aus oder legt sie an und baut den Tracking-Code ein. Vor dem Schreiben zeigt sie einen Diff, ein zweiter Lauf fügt nie ein zweites Snippet ein, und npx puremetrix@latest remove stellt Ihre Dateien wieder her.

• Ohne Anmeldung: npx puremetrix@latest init --key pk_… --domain example.com
• Als npm-Paket statt Script-Tag: npx puremetrix@latest init --mode package. Die CLI installiert dann @puremetrix/tracker ab Version 0.3 und baut bei Next.js den PureMetrixProvider aus @puremetrix/tracker/next ein (app/layout.tsx oder pages/_app.tsx). Ein erneuter Lauf bringt ältere Einbauten auf den neuen Stand.
• Nur ansehen: npx puremetrix@latest init --dry-run
• Einbau prüfen: npx puremetrix@latest doctor
• CI und KI-Agenten: CI-Token unter Einstellungen → Verbundene Apps erstellen und als PUREMETRIX_TOKEN übergeben; ohne Terminal bricht die CLI ohne Token sofort ab (Exit-Code 2). Zweistufige Anmeldung: login --json, dann login --complete.
• Sprache: wird aus Ihrem System übernommen, sonst --lang de

Verbundene Geräte und CI-Tokens sehen und widerrufen Sie unter Einstellungen → Verbundene Apps. Handbuch: app.puremetrix.org/de/help/cli

License

MIT © Lydia Rebers