Marketing

PP Clarity

pp-clarity

Client-side instrumentation helpers for Microsoft Clarity.

Printed by @cathrynlavery (Cathryn Lavery)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install clarity

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-clarity --force

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

OpenClaw

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

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

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

Generate and audit Microsoft Clarity browser instrumentation from the terminal.

Microsoft Clarity's client API is made of JavaScript calls and HTML attributes, so this CLI treats it as an instrumentation assistant instead of a fake REST wrapper. It can fetch the public tag script, render copy-safe snippets, and audit local HTML for the calls Microsoft documents.

Learn more at PP Clarity.

Authentication

No server API token is required for the documented Clarity client API. Your Clarity project ID is embedded in the browser tracking snippet and acts as the setup key for client-side instrumentation.

The Data Export API does use a bearer token. Generate it in Microsoft Clarity under Settings -> Data Export -> Generate new API token, then keep it out of chat and source control:

export PP_CLARITY_API_TOKEN="..."

For local testing with an agent, a token file is usually easier because the agent can read the same filesystem but not your shell environment:

mkdir -p ~/.config/clarity-pp-cli
printf '%s' 'YOUR_TOKEN_HERE' > ~/.config/clarity-pp-cli/api-token
chmod 600 ~/.config/clarity-pp-cli/api-token

clarity-pp-cli insights live also accepts MICROSOFT_CLARITY_API_TOKEN, CLARITY_API_TOKEN, or PP_CLARITY_API_TOKEN_FILE.

Quick Start

# Render the install snippet for your Clarity project ID.
clarity-pp-cli snippet install abc123 --format html

# Generate a custom identifiers call.
clarity-pp-cli snippet identify user-42 --session-id sess-9 --page-id checkout --friendly-name "Paid customer"

# Check local HTML before deployment.
clarity-pp-cli audit html ./index.html --json --select found_project_id,calls

# Fetch live dashboard export data using PP_CLARITY_API_TOKEN.
clarity-pp-cli insights live --days 1 --dimension OS --json

Unique Features

These capabilities aren't available in any other tool for this API.

Instrumentation authoring

snippet install — Render a complete Clarity tracking snippet for a project ID, plus focused snippets for every documented client API call.

Use this when adding Clarity to a site or handing implementation-ready code to another agent.
```
clarity-pp-cli snippet install abc123 --format html
```

Instrumentation review

audit html — Inspect an HTML file for a Clarity tag script, masking attributes, and common window.clarity client API calls.

Use this before shipping page changes that are supposed to include Clarity instrumentation.
```
clarity-pp-cli audit html ./index.html --json --select found_project_id,calls
```

Usage

Run clarity-pp-cli --help for the full command reference and flag list.

Commands

insights

Read Microsoft Clarity Data Export API insights.

clarity-pp-cli insights live - Fetch project live insights from the Microsoft Clarity Data Export API.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
clarity-pp-cli tag mock-value

# JSON for scripting and agents
clarity-pp-cli tag mock-value --json

# Filter to specific fields
clarity-pp-cli tag mock-value --json --select id,name,status

# Dry run — show the request without sending
clarity-pp-cli tag mock-value --dry-run

# Agent mode — JSON + compact + no prompts in one flag
clarity-pp-cli tag mock-value --agent

Live Data Export

The Data Export API is read-only but quota-limited by Microsoft to 10 requests per project per day. Use --dry-run first to verify the exact request without spending quota:

clarity-pp-cli insights live --days 1 --dimension OS --dry-run
clarity-pp-cli insights live --days 1 --dimension OS --json

Agent Usage

This CLI is designed for AI agent consumption:

Non-interactive - never prompts, every input is a flag
Pipeable - --json output to stdout, errors to stderr
Filterable - --select id,name returns only fields you need
Previewable - --dry-run shows the request without sending
Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
Offline-friendly - sync/search commands can use the local SQLite store when available
Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.

Health Check

clarity-pp-cli doctor

Verifies configuration and connectivity to the API.

Configuration

Config file: ~/.config/clarity-pp-cli/config.toml

Troubleshooting

Not found errors (exit code 3)

Check the resource ID is correct
Run the list command to see available items

API-specific

No sessions appear in Clarity after install — Confirm the project ID in the generated snippet matches the project under Settings -> Setup and check for POST requests to https://www.clarity.ms/collect in the browser network panel.
Sensitive content appears masked or unmasked unexpectedly — Use snippet mask to generate the exact data-clarity-mask or data-clarity-unmask attribute and audit the HTML to confirm it is present on the intended element.

Sources & Inspiration

This CLI was built by studying these projects and resources:

Generated by CLI Printing Press