pp-posthog

PostHog — Printing Press 命令行工具

前提条件：安装命令行工具

此技能使用 posthog-pp-cli 二进制文件。**调用此技能中的任何命令前，必须确认命令行工具已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

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

2. 验证：posthog-pp-cli --version
3. 确保报告的安装目录已加入将调用此技能的 Agent/运行时的 $PATH。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/developer-tools/posthog/cmd/posthog-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功前，请勿执行此技能中的命令。

何时使用此命令行工具

当 Agent 任务需要跨多个资源类型查询、比较差异或组合 PostHog 数据时，请使用 posthog-pp-cli，例如标志状态与错误事件、LLM 成本与变体表现、实验曝光与显著性。与 Web UI 相比，它处理批量读取更快，并能生成结构化 JSON，供 Agent 直接使用，无需解析 HTML。

独特功能

这些功能在此 API 的其他任何工具中都不可用。

标志安全性

• flags blast-radius — 在归档或重命名标志前，查找所有引用该标志的洞察、仪表板、实验和调查。

  在归档或重命名标志前使用，避免意外导致仪表板和实验失效。

  posthog-pp-cli flags blast-radius --key my-checkout-v2 --json
  

• flags rollout-health — 判断标志逐步放量是否可以继续：根据标志曝光情况，关联错误率和关键指标变化，评估把握。

  在将标志放量至 100% 前使用，以发现整体指标中看不出来的回归。

  posthog-pp-cli flags rollout-health --key new-checkout --window 24h --agent
  

• flags stale — 列出 N 天内未评估过的标志，找出可在它们不断累积前清理的候选项。

  在季度标志清理冲刺中使用，安全地识别无效代码路径。

  posthog-pp-cli flags stale --days 30 --json
  

LLM 可观测性

• llm cost-attribution — 按功能标志变体拆分 LLM 支出，查看昂贵的模型变体是否物有所值。

  评估是否应根据实际的每次转化成本，推广更昂贵的 LLM 变体时使用。

  posthog-pp-cli llm cost-attribution --flag model-tier --agent
  

可持续积累的本地状态

• persons at-risk — 找出队列中哪些用户逐渐不活跃且近期遇到过错误，以便在他们流失前采取行动。

  在每周留存评审中使用，优先主动联系用户，避免他们流失。

  posthog-pp-cli persons at-risk --cohort paying-users --silent-days 14 --json
  

• events property-drift — 捕捉埋点回归：找出某个事件在两个时间窗口之间悄然消失的属性。

  部署后使用，捕捉可能破坏进行中实验和仪表板的隐性架构变更。

  posthog-pp-cli events property-drift checkout_completed --agent
  

• experiments pre-check — 提前判断某项实验能否在本冲刺期间达到显著性，或是否需要立即调整流量。

  在每个冲刺开始时使用，找出需要调整流量、以免错过时限的实验。

  posthog-pp-cli experiments pre-check --agent
  

• dashboard health — 在干系人会议前找出故障仪表板，包括数据过时、队列已删除或标志已归档等问题。

  在每周业务评审前使用，找出故障的洞察卡片，避免数据团队陷入尴尬。

  posthog-pp-cli dashboard health --stale-days 7 --agent
  

命令参考

projects — 管理项目

public-hog-function-templates — 管理公开的 hog 函数模板

• posthog-pp-cli public-hog-function-templates — 列出

user-home-settings — 管理用户主页设置

• posthog-pp-cli user-home-settings partial-update — 更新已通过身份验证的用户在当前团队中固定的侧边栏标签页和/或主页。将 @me 作为 UUID 传入....
• posthog-pp-cli user-home-settings retrieve — 获取已通过身份验证的用户在当前团队中固定的侧边栏标签页和已配置的主页。将 @me 作为 UUID 传入。

users — 管理用户

• posthog-pp-cli users cancel-email-change-request-partial-update — 取消电子邮件更改请求的部分更新
• posthog-pp-cli users destroy — 删除
• posthog-pp-cli users list — 列出
• posthog-pp-cli users partial-update — 更新已通过身份验证的用户的一个或多个个人资料字段或设置。
• posthog-pp-cli users request-email-verification-create — 创建电子邮件验证请求
• posthog-pp-cli users retrieve — 获取用户的个人资料和设置。将 @me 作为 UUID 传入以获取已通过身份验证的用户；非员工调用者……
• posthog-pp-cli users update — 替换已通过身份验证的用户的个人资料和设置。将 @me 作为 UUID 传入以更新已通过身份验证的用户……
• posthog-pp-cli users verify-email-create — 创建电子邮件验证

查找合适的命令

知道要做什么，但不清楚该用哪个命令时，可以直接询问 CLI：

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

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项，此时可改用 --help 或更具体的查询。

配方

查找可安全归档的标记

posthog-pp-cli flags stale --days 60 --json | jq '.[].key'

列出过去 60 天内没有评估事件的标记键——可安全清理的候选项

扩大流量前的安全检查

posthog-pp-cli flags rollout-health --key new-checkout --window 48h --agent --select flag_key,error_rate_delta,metric_delta

在将标记流量提升至 100% 前，检查标记曝光用户的错误率和购买指标变化

每周实验简报

posthog-pp-cli experiments pre-check --json | jq '.[] | {key, winner, significance, days_remaining}'

跨实验预检查摘要，供周一站会使用——找出需要调整流量的实验

按标记变体统计 LLM 成本

posthog-pp-cli llm cost-attribution --flag model-tier --since 2026-08-01 --agent --select variant,total_cost_usd,avg_cost_per_call

比较 A/B 变体的 LLM 支出，以判断在你的场景中 GPT-4o 是否优于 GPT-4o-mini

全员大会前的仪表板审计

posthog-pp-cli dashboard health --stale-days 7 --json | jq '.[] | select(.issues | length > 0)'

在向利益相关者演示前，找出筛选器失效或数据过时的仪表板

身份验证设置

使用你的 PostHog 个人 API 密钥（phx_...）。设置 POSTHOG_API_KEY，或运行 posthog-pp-cli auth set-token <token>。通过 POSTHOG_HOST 支持 US（app.posthog.com）和 EU（eu.posthog.com）实例。

运行 posthog-pp-cli doctor 验证设置。

Agent 模式

为任意命令添加 --agent。该选项会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于冗长 API，此功能对精简上下文至关重要：

  posthog-pp-cli flags stale --agent --select key,days_stale
  

• 可预览 — --dry-run 显示请求，但不会发送

• 适合离线使用 — 有本地 SQLite 存储时，同步/搜索命令可使用该存储

• 非交互式 — 从不提示输入，所有输入都通过标志传入

• 显式重试 — 仅当已存在的创建对象应视为成功时才使用 --idempotent；仅当缺失的删除目标应视为成功时才使用 --ignore-missing

响应封装

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

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

解析 .results 获取数据，并检查 .meta.source 以确认数据来自实时来源还是本地来源。只有当 stdout 连接到终端时，才会向 stderr 输出人类可读的 N results (live) 摘要；通过管道传输或由 Agent 消费时，stdout 只输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有什么不对劲时，请记录下来：

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

条目会保存在本地的 ~/.posthog-pp-cli/feedback.jsonl 中。除非设置了 POSTHOG_FEEDBACK_ENDPOINT，并且传入 --send 或设置 POSTHOG_FEEDBACK_AUTO_SEND=true，否则绝不会 POST。默认行为仅保存到本地。

记录让你感到意外的事情，而不是提交 Bug 报告。简短、具体，写成一行：这才是会不断累积的部分。

输出交付

每条命令都接受 --deliver <sink>。除了（或代替）标准输出，结果还会发送到指定的接收目标，这样 Agent 就能路由命令结果，而无需手动通过管道传递。支持三种接收目标：

接收目标	效果
stdout	默认；仅写入标准输出
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（当使用 --compact 时，格式为 application/json 或 application/x-ndjson）

遇到未知方案时会拒绝执行，并返回列出支持方案的结构化错误。Webhook 失败时会返回非零退出码，并在标准错误中记录 URL 和 HTTP 状态。

命名配置

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

posthog-pp-cli profile save briefing --json
posthog-pp-cli --profile briefing flags stale
posthog-pp-cli profile list --json
posthog-pp-cli profile show briefing
posthog-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，让进行自省的 Agent 能在运行时发现它们。

退出码

代码	含义
0	成功
2	用法错误（参数不正确）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 posthog-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上方的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并带上 --agent）

安装 MCP 服务

从此 CLI 已发布的公共库条目或预构建版本中安装 MCP 二进制文件，然后注册它：

claude mcp add posthog-pp-mcp -- posthog-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which posthog-pp-cli 如果未找到，请提供安装选项（参见本技能顶部的先决条件）。
2. 根据用户查询，从上方的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

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

4. 如果有歧义，请查看子命令帮助：posthog-pp-cli <command> --help。