pp-clarity

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PP Clarity — Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装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:

Install via the Printing Press installer:

bash

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

Verify:
```
clarity-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

If the

npx

install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):

bash

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

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

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.

本技能基于

clarity-pp-cli

二进制文件运行。在调用本技能的任何命令之前，必须确认CLI已安装。如果未安装，请先执行以下步骤：

通过Printing Press安装程序安装：

bash

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

验证安装：
```
clarity-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

如果

npx

安装失败（无Node环境、离线等情况），可以改用Go直接安装（要求Go 1.23及以上版本）：

bash

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

如果安装后执行

--version

提示“command not found”，说明安装程序未将二进制文件添加到

$PATH

中。请在验证成功前不要执行本技能的命令。

Microsoft Clarity的客户端API由JavaScript调用和HTML属性组成，因此本CLI工具作为埋点助手，而非模拟REST包装器。它可以获取公开的标签脚本、生成可直接复制使用的代码片段，并审核本地HTML文件中是否包含Microsoft官方文档中提到的调用。

When to Use This CLI

何时使用本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.

当你需要添加、检查或解释Microsoft Clarity浏览器埋点代码时，可以使用本CLI工具。它最擅长生成代码片段和审核本地HTML文件；但它不能替代Clarity控制台。

When Not to Use This CLI

何时不使用本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.

请勿在需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或更改远程状态的请求中使用本CLI工具。本CLI仅提供用于检查、导出、同步和分析的只读命令。

Unique Capabilities

独特功能

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

这些功能是其他同类型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.
bash
```
clarity-pp-cli snippet install abc123 --format html
```

snippet install
— 为指定项目ID生成完整的Clarity跟踪代码片段，同时为每个已文档化的客户端API调用生成针对性的代码片段。
当你需要为网站添加Clarity埋点，或向其他Agent提供可直接实现的代码时使用此命令。
bash
```
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.
bash
```
clarity-pp-cli audit html ./index.html --json --select found_project_id,calls
```

audit html
— 检查HTML文件中是否包含Clarity标签脚本、掩码属性以及常见的window.clarity客户端API调用。
当你准备上线包含Clarity埋点的页面变更前，使用此命令进行检查。
bash
```
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

tag — 查看Microsoft Clarity跟踪标签脚本

```
clarity-pp-cli tag <project_id>
```
— 获取指定项目ID的Clarity跟踪标签脚本

手动编写的命令

```
clarity-pp-cli snippet install
```
— 为Clarity项目ID生成跟踪代码片段
```
clarity-pp-cli snippet consent
```
— 生成Cookie授权客户端API调用代码
```
clarity-pp-cli snippet identify
```
— 生成自定义标识符客户端API调用代码
```
clarity-pp-cli snippet set
```
— 生成自定义标签客户端API调用代码
```
clarity-pp-cli snippet event
```
— 生成自定义事件客户端API调用代码
```
clarity-pp-cli snippet upgrade
```
— 生成会话优先级客户端API调用代码
```
clarity-pp-cli snippet mask
```
— 生成Clarity掩码或取消掩码HTML属性代码
```
clarity-pp-cli audit html
```
— 检查HTML文件中是否包含Clarity安装代码片段和客户端API调用
```
clarity-pp-cli insights live
```
— 获取Microsoft Clarity数据导出API的实时洞察数据

Finding the right command

查找合适的命令

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

bash

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

means at least one match; exit code

means no confident match — fall back to

--help

or use a narrower query.

当你知道要执行的操作但不知道对应的命令时，可以直接询问CLI：

bash

clarity-pp-cli which "<用你自己的语言描述功能>"

which

命令会将自然语言的功能查询解析为与本CLI精选功能索引最匹配的命令。退出码

表示至少找到一个匹配项；退出码

表示没有找到确定的匹配项——此时可以改用

--help

或更精确的查询语句。

Recipes

使用示例

Install Clarity

安装Clarity

bash

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

Produces the tracking snippet that belongs in the page head.

bash

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

生成可添加到页面头部的跟踪代码片段。

Add a custom event

添加自定义事件

bash

clarity-pp-cli snippet event newsletterSignup

Produces the documented event call for a named user action.

bash

clarity-pp-cli snippet event newsletterSignup

生成针对指定用户操作的已文档化事件调用代码。

Audit only high-gravity fields

仅审核关键字段

bash

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

Narrows audit output for agent consumption.

bash

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

缩小审核输出范围，方便Agent处理。

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:

bash

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

For local agent testing, prefer the local token file:

bash

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.

客户端代码片段命令仅需公开的Clarity项目ID。

对于数据导出API的读取操作，需要在环境变量中设置令牌。请勿将令牌值粘贴到聊天中或提交到文件：

bash

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

对于本地Agent测试，建议使用本地令牌文件：

bash

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

该命令也支持

MICROSOFT_CLARITY_API_TOKEN

、

CLARITY_API_TOKEN

或

PP_CLARITY_API_TOKEN_FILE

环境变量。

执行

clarity-pp-cli doctor

验证设置是否正确。

Agent Mode

Agent模式

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:
bash
```
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

在任何命令后添加

--agent

参数。该参数等价于：

--json --compact --no-input --no-color --yes

。

可管道传输 — 标准输出为JSON，错误信息输出到标准错误
可过滤 —
```
--select
```
参数保留指定字段子集。点路径可深入嵌套结构；数组会遍历每个元素。这在处理冗长API时对缩小上下文范围至关重要：
bash
```
clarity-pp-cli tag mock-value --agent --select id,name,status
```
可预览 —
```
--dry-run
```
参数显示请求内容但不发送
离线友好 — 同步/搜索命令在本地SQLite存储可用时可使用该存储
非交互式 — 从不提示用户，所有输入均通过标志参数提供
只读 — 请勿使用本CLI执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会修改状态的请求

Response envelope

响应包

Commands that read from the local store or the API wrap output in a provenance envelope:

json

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse

.results

for data and

.meta.source

to know whether it's live or local. A human-readable

N results (live)

summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.

从本地存储或API读取数据的命令会将输出包装在来源信息包中：

json

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析

.results

获取数据，通过

.meta.source

判断数据是实时还是本地的。只有当标准输出为终端时，才会向标准错误输出人类可读的

N results (live)

摘要；管道/Agent消费者仅会在标准输出获取纯JSON内容。

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:

clarity-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
clarity-pp-cli feedback --stdin < notes.txt
clarity-pp-cli feedback list --json --limit 10

Entries are stored locally at

~/.clarity-pp-cli/feedback.jsonl

. They are never POSTed unless

CLARITY_CLIENT_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

CLARITY_CLIENT_FEEDBACK_AUTO_SEND=true

. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

当你（或Agent）发现本CLI存在问题时，可以记录反馈：

clarity-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
clarity-pp-cli feedback --stdin < notes.txt
clarity-pp-cli feedback list --json --limit 10

反馈条目会存储在本地

~/.clarity-pp-cli/feedback.jsonl

文件中。除非设置了

CLARITY_CLIENT_FEEDBACK_ENDPOINT

且传递了

--send

参数或设置了

CLARITY_CLIENT_FEEDBACK_AUTO_SEND=true

，否则反馈不会被POST发送。默认行为仅存储在本地。

请记录让你感到意外的内容，而非正式的错误报告。简短、具体、单行描述：这样的反馈更有价值。

Output Delivery

输出交付

Every command accepts

--deliver <sink>

. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
`stdout`	Default; write to stdout only
`file:<path>`	Atomically write output to `<path>` (tmp + rename)
`webhook:<url>`	POST the output body to the URL ( `application/json` or `application/x-ndjson` when `--compact` )

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

每个命令都支持

--deliver <sink>

参数。输出会发送到指定的目标，同时（或替代）标准输出，因此Agent无需手动管道即可路由命令结果。支持三种目标：

目标	效果
`stdout`	默认值；仅输出到标准输出
`file:<path>`	原子性地将输出写入 `<path>` （先写入临时文件再重命名）
`webhook:<url>`	将输出体POST到指定URL（当使用 `--compact` 时为 `application/json` 或 `application/x-ndjson` 格式）

不支持的协议会返回结构化错误，并列出支持的协议类型。Webhook失败时会返回非零退出码，并在标准错误中记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

clarity-pp-cli profile save briefing --json
clarity-pp-cli --profile briefing tag mock-value
clarity-pp-cli profile list --json
clarity-pp-cli profile show briefing
clarity-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults.

agent-context

lists all available profiles under

available_profiles

so introspecting agents discover them at runtime.

配置文件是一组保存的标志值，可在多次调用中复用。当定时Agent每次运行都使用相同配置调用同一命令时，可以使用此功能——即HeyGen的“Beacon”模式。

clarity-pp-cli profile save briefing --json
clarity-pp-cli --profile briefing tag mock-value
clarity-pp-cli profile list --json
clarity-pp-cli profile show briefing
clarity-pp-cli profile delete briefing --yes

显式标志始终优先于配置文件中的值；配置文件值优先于默认值。

agent-context

会在

available_profiles

下列出所有可用配置文件，以便自省Agent在运行时发现它们。

Exit Codes

退出码

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

代码	含义
0	成功
2	使用错误（参数错误）
3	资源未找到
5	API错误（上游问题）
7	速率限制（等待后重试）
10	配置错误

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
→ show
```
clarity-pp-cli --help
```
output
Starts with
install
→ ends with
```
mcp
```
→ MCP installation; otherwise → see Prerequisites above
Anything else → Direct Use (execute as CLI command with
```
--agent
```
)

解析

$ARGUMENTS

的规则：

为空、
help
或
--help
→ 显示
```
clarity-pp-cli --help
```
输出
以
install
开头 → 若结尾为
```
mcp
```
→ 安装MCP；否则 → 参见上方的前提条件部分
其他情况 → 直接使用（以
```
--agent
```
标志执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP server:

bash

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

bash

claude mcp add clarity-pp-mcp -- clarity-pp-mcp

Verify:
```
claude mcp list
```

安装MCP服务器：

bash

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

注册到Claude Code：

bash

claude mcp add clarity-pp-mcp -- clarity-pp-mcp

验证：
```
claude mcp list
```

Direct Use

直接使用

Check if installed:
```
which clarity-pp-cli
```
If not found, offer to install (see Prerequisites at the top of this skill).
Match the user query to the best command from the Unique Capabilities and Command Reference above.

Execute with the

--agent

flag:

bash

clarity-pp-cli <command> [subcommand] [args] --agent

If ambiguous, drill into subcommand help:
```
clarity-pp-cli <command> --help
```
.

检查是否已安装：
```
which clarity-pp-cli
```
如果未找到，提供安装选项（参见顶部前提条件部分）。
将用户查询与上方“独特功能”和“命令参考”中的最佳匹配命令对应。

使用

--agent

标志执行命令：

bash

clarity-pp-cli <command> [subcommand] [args] --agent

如果存在歧义，查看子命令帮助：
```
clarity-pp-cli <command> --help
```
。