pp-clarity

PP Clarity — Printing Press CLI

前提条件：CLI をインストールする

このスキルでは、clarity-pp-cli バイナリを使用します。**このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。**インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使ってインストールします。バイナリの既定のインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin です。

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

2. 確認します：clarity-pp-cli --version
3. 報告されたインストール先ディレクトリが、このスキルを実行するエージェント／ランタイムの $PATH に含まれていることを確認します。

npx でのインストールに失敗した場合（Node がない、オフラインなど）は、Go を直接インストールしてください（Go 1.26.6 以降が必要です）。

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

インストール後に --version が「command not found」と報告する場合、ランタイムからバイナリのディレクトリを $PATH 経由で参照できていません。確認が成功するまで、スキルのコマンドを実行しないでください。

この CLI を使用する場面

Microsoft Clarity のブラウザー計測を追加、レビュー、または説明する必要がある場合に、この CLI を使用します。スニペットの生成とローカル HTML の監査に特に適しています。Clarity ダッシュボードの代わりにはなりません。

この CLI を使用しない場面

リモートの状態の作成、更新、削除、公開、コメント、賛成票の投票、招待、注文、メッセージの送信、予約、購入、または変更が必要なリクエストでは、この CLI を起動しないでください。この印刷用 CLI には、検査、エクスポート、同期、分析のための読み取り専用コマンドが用意されています。

独自の機能

この API では、これらの機能を利用できるツールはほかにありません。

計測コードの作成

• snippet install — プロジェクト ID 用の Clarity トラッキングスニペット一式と、ドキュメントに記載された各クライアント API 呼び出しの専用スニペットを生成します。

  サイトに Clarity を追加するときや、実装に使えるコードを別のエージェントに渡すときに使用します。

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

計測コードのレビュー

• audit html — HTML ファイルを調べ、Clarity タグスクリプト、マスキング属性、よく使われる window.clarity クライアント API 呼び出しを確認します。

  Clarity の計測コードを含める予定のページ変更をリリースする前に使用します。

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

コマンドリファレンス

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 — Clarity のインストールスニペットとクライアント API 呼び出しが HTML ファイルに含まれているか確認します
• clarity-pp-cli insights live — Microsoft Clarity Data Export API のライブインサイトを取得します

適切なコマンドを見つける

実行したいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接問い合わせます。

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

which は自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 つ一致したことを示します。終了コード 2 は確信できる一致がなかったことを示します。その場合は --help に切り替えるか、より具体的な問い合わせを使用してください。

レシピ

Clarity をインストールする

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

ページの head に追加するトラッキングスニペットを生成します。

カスタムイベントを追加する

clarity-pp-cli snippet event newsletterSignup

指定したユーザー操作に対応する、ドキュメント記載のイベント呼び出しを生成します。

重要度の高いフィールドのみを監査する

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

エージェントが扱いやすいよう、監査結果の出力を絞り込みます。

認証の設定

クライアント側のスニペットコマンドで必要なのは、公開されている Clarity プロジェクト ID のみです。

Data Export API から読み取る場合は、環境変数にトークンを設定してください。トークンの値をチャットに貼り付けたり、ファイルにコミットしたりしないでください。

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

ローカルでエージェントをテストする場合は、ローカルトークンファイルを使用してください。

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 を追加します。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプ可能 — stdout には JSON、stderr にはエラーが出力されます

• フィルタ可能 — --select でフィールドを絞り込めます。ドット区切りのパスはネストされた構造をたどり、配列では各要素を順にたどります。出力が冗長な API でコンテキストを小さく保つために重要です。

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

• プレビュー可能 — --dry-run で送信せずにリクエストを表示します

• オフライン対応 — 同期／検索コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトは表示されず、すべての入力はフラグで指定します

• 読み取り専用 — 作成、更新、削除、公開、コメント、賛成票、招待、注文、送信、その他の変更を伴うリクエストには、この CLI を使用しないでください

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力を出典情報のエンベロープでラップします。

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

データには .results を解析し、ライブデータかローカルデータかを確認するには .meta.source を参照してください。人間が読みやすい N results (live) の概要は、stdout がターミナルの場合にのみ stderr に出力されます。パイプ経由またはエージェントの利用者には、stdout に純粋な JSON が出力されます。

エージェントからのフィードバック

あなた（またはエージェント）がこの 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 されることはありません。デフォルトではローカルにのみ保存されます。

バグ報告ではなく、意外に感じたことを書いてください。短く、具体的に、一行で記述してください。それが積み重なっていきます。

出力先

すべてのコマンドで --deliver <sink> を指定できます。出力は stdout への出力に加えて（または stdout の代わりに）、指定したシンクにも送られるため、エージェントはコマンド結果を手作業でパイプしなくても振り分けられます。対応しているシンクは 3 種類です。

シンク	動作
stdout	デフォルト。stdout のみに出力します
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイルを作成してからリネームします）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

不明なスキームは、対応するスキームを示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードが返され、URL と HTTP ステータスが stderr に記録されます。

名前付きプロファイル

プロファイルは、呼び出しのたびに再利用できるフラグ値の保存セットです。スケジュールされたエージェントが毎回同じ設定で同じコマンドを呼び出す場合に使用してください。これは 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 に一覧表示します。

終了コード

コード	意味
0	成功
2	使用方法エラー（引数が正しくありません）
3	リソースが見つかりません
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → clarity-pp-cli --help の出力を表示します
2. install で始まる場合 → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の前提条件を参照してください
3. それ以外 → 直接使用（CLI コマンドとして --agent を付けて実行します）

MCP サーバーのインストール

1. MCP サーバーをインストールします。

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

2. Claude Code に登録します。

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

3. 確認します：claude mcp list

直接使用

1. インストール済みか確認します：which clarity-pp-cli 見つからない場合は、インストールを案内します（このスキルの冒頭にある前提条件を参照してください）。
2. ユーザーのクエリに最適なコマンドを、上記の「独自の機能とコマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します：

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

4. 不明な点がある場合は、サブコマンドのヘルプを確認します：clarity-pp-cli <command> --help。