Pp Clarity

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/marketing/clarity/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

PP Clarity — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the clarity-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

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

2. Verify: clarity-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):

go install github.com/mvanhorn/printing-press-library/library/marketing/clarity/cmd/clarity-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

When to Use This CLI

Use this CLI when you need to add, review, or explain Microsoft Clarity browser instrumentation. It is strongest for generating snippets and auditing local HTML; it is not a replacement for the Clarity dashboard.

When Not to Use This CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis.

Unique Capabilities

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

Command Reference

tag — Inspect the Microsoft Clarity tracking tag script

• clarity-pp-cli tag <project_id> — Fetch the Clarity tracking tag script for a project ID

Hand-written commands

• clarity-pp-cli snippet install — Render the tracking snippet for a Clarity project ID
• clarity-pp-cli snippet consent — Render the Cookie consent client API call
• clarity-pp-cli snippet identify — Render the custom identifiers client API call
• clarity-pp-cli snippet set — Render the custom tags client API call
• clarity-pp-cli snippet event — Render the custom event client API call
• clarity-pp-cli snippet upgrade — Render the session-priority client API call
• clarity-pp-cli snippet mask — Render Clarity mask or unmask HTML attributes
• clarity-pp-cli audit html — Check an HTML file for a Clarity install snippet and client API calls
• clarity-pp-cli insights live — Fetch Microsoft Clarity Data Export API live insights

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

clarity-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.

Recipes

Install Clarity

clarity-pp-cli snippet install abc123 --format html

Produces the tracking snippet that belongs in the page head.

Add a custom event

clarity-pp-cli snippet event newsletterSignup

Produces the documented event call for a named user action.

Audit only high-gravity fields

clarity-pp-cli audit html ./index.html --json --select found_project_id,calls,mask_count,unmask_count

Narrows audit output for agent consumption.

Auth Setup

Client-side snippet commands only need the public Clarity project ID.

For Data Export API reads, set a token in the environment. Do not paste token values into chat or commit them to files:

export PP_CLARITY_API_TOKEN="..."
clarity-pp-cli insights live --days 1 --dimension OS --json

For local agent testing, prefer the local token file:

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

The command also accepts MICROSOFT_CLARITY_API_TOKEN, CLARITY_API_TOKEN, or PP_CLARITY_API_TOKEN_FILE.

Run clarity-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr

• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  clarity-pp-cli tag mock-value --agent --select id,name,status

• Previewable — --dry-run shows the request without sending

• Offline-friendly — sync/search commands can use the local SQLite store when available

• Non-interactive — never prompts, every input is a flag

• Read-only — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests