Microsoft Clarity CLI

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.

Created by @cathrynlavery (Cathryn Lavery).

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

tag

Inspect the Microsoft Clarity tracking tag script

• clarity-pp-cli tag get - Fetch the Clarity tracking tag script for a project ID

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:

• Microsoft Learn Clarity client API reference
• Microsoft Learn Clarity setup guide

Generated by CLI Printing Press