pp-posthog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog — Printing Press CLI

Prerequisites: Install the CLI

前置条件：安装CLI

This skill drives the

posthog-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-library install posthog --cli-only

Verify:
```
posthog-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.26.3 or newer):

bash

go install github.com/mvanhorn/printing-press-library/library/developer-tools/posthog/cmd/posthog-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.

此Skill驱动

posthog-pp-cli

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

通过Printing Press安装程序安装：

bash

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

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

如果

npx

安装失败（无Node环境、离线等），可回退到直接通过Go安装（要求Go 1.26.3或更高版本）：

bash

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

如果安装后执行

--version

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

$PATH

中。请在验证成功前不要执行Skill命令。

When to Use This CLI

何时使用此CLI

Use posthog-pp-cli when an agent task requires querying, diffing, or combining PostHog data across more than one resource type — flag state vs error events, LLM costs vs variant performance, experiment exposure vs significance. It is faster than the web UI for bulk reads and produces structured JSON that agents can consume directly without parsing HTML.

当Agent任务需要跨多种资源类型查询、对比或整合PostHog数据时（例如标志状态与错误事件、LLM成本与变体性能、实验曝光度与显著性），请使用posthog-pp-cli。它在批量读取方面比Web UI更快，并且能生成结构化JSON，Agent可直接解析无需处理HTML。

Unique Capabilities

独特功能

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

以下功能是其他同类API工具所不具备的：

Flag safety

功能标志安全性

flags blast-radius
— Find every insight, dashboard, experiment, and survey that references a flag before you archive or rename it.
Use before archiving or renaming a flag to prevent breaking dashboards and experiments silently.
bash
```
posthog-pp-cli flags blast-radius --key my-checkout-v2 --json
```
flags rollout-health
— Go/no-go confidence for a flag ramp — error rate and key metric movement correlated with flag exposure.
Use before ramping a flag to 100% to catch regressions that aren't visible in overall metrics.
bash
```
posthog-pp-cli flags rollout-health --key new-checkout --window 24h --agent
```
flags stale
— List flags that haven't been evaluated in N days — cleanup candidates before they accumulate.
Use in quarterly flag cleanup sprints to identify dead code paths safely.
bash
```
posthog-pp-cli flags stale --days 30 --json
```

flags blast-radius
— 在归档或重命名标志前，查找所有引用该标志的洞察、仪表盘、实验和调查。
在归档或重命名标志前使用，以避免静默破坏仪表盘和实验。
bash
```
posthog-pp-cli flags blast-radius --key my-checkout-v2 --json
```
flags rollout-health
— 为标志放量提供放行/拒绝的置信度——关联标志曝光度的错误率和关键指标变化。
在将标志放量至100%前使用，以捕捉整体指标中无法体现的回归问题。
bash
```
posthog-pp-cli flags rollout-health --key new-checkout --window 24h --agent
```
flags stale
— 列出N天内未被评估的标志——作为清理候选，避免堆积。
在季度标志清理迭代中使用，以安全识别废弃代码路径。
bash
```
posthog-pp-cli flags stale --days 30 --json
```

LLM observability

LLM可观测性

llm cost-attribution
— Break down LLM spend by feature flag variant — see whether the expensive model variant pays for itself.
Use when evaluating whether to promote a more expensive LLM variant based on actual cost-per-conversion.
bash
```
posthog-pp-cli llm cost-attribution --flag model-tier --agent
```

llm cost-attribution
— 按功能标志变体拆分LLM支出——查看高成本模型变体是否物有所值。
在评估是否推广更昂贵的LLM变体时使用，基于实际转化成本判断。
bash
```
posthog-pp-cli llm cost-attribution --flag model-tier --agent
```

Local state that compounds

可累积的本地状态

persons at-risk
— Surface which users in a cohort are going quiet and recently hit errors — before they churn.
Use in weekly retention reviews to prioritize proactive outreach before churn events.
bash
```
posthog-pp-cli persons at-risk --cohort paying-users --silent-days 14 --json
```
events property-drift
— Catch tracking regressions — properties that silently disappeared from an event between two time windows.
Use after a deploy to catch silent schema changes that corrupt ongoing experiments and dashboards.
bash
```
posthog-pp-cli events property-drift checkout_completed --agent
```
experiments pre-check
— Know today whether an experiment will reach significance this sprint, or needs traffic adjustment now.
Use at the start of each sprint to surface experiments that need traffic changes before they run out of time.
bash
```
posthog-pp-cli experiments pre-check --agent
```
dashboard health
— Find broken dashboards before a stakeholder meeting does — stale data, deleted cohorts, archived flags.
Use before weekly business reviews to catch broken insight tiles that would embarrass the data team.
bash
```
posthog-pp-cli dashboard health --stale-days 7 --agent
```

persons at-risk
— 识别群组中活跃度下降且近期遇到错误的用户——在他们流失前进行干预。
在每周留存评审中使用，优先安排主动触达以防止用户流失。
bash
```
posthog-pp-cli persons at-risk --cohort paying-users --silent-days 14 --json
```
events property-drift
— 捕捉跟踪回归问题——两个时间窗口间事件中悄然消失的属性。
在部署后使用，捕捉会破坏正在进行的实验和仪表盘的静默 schema 变更。
bash
```
posthog-pp-cli events property-drift checkout_completed --agent
```
experiments pre-check
— 提前知晓实验在当前迭代内是否能达到显著性，或是否需要立即调整流量。
在每个迭代开始时使用，识别需要调整流量的实验，避免时间耗尽。
bash
```
posthog-pp-cli experiments pre-check --agent
```
dashboard health
— 在利益相关者会议前发现损坏的仪表盘—— stale数据、已删除的群组、已归档的标志。
在每周业务评审前使用，避免数据团队因损坏的洞察面板陷入尴尬。
bash
```
posthog-pp-cli dashboard health --stale-days 7 --agent
```

Command Reference

命令参考

projects — Manage projects

public-hog-function-templates — Manage public hog function templates

posthog-pp-cli public-hog-function-templates

— List

user-home-settings — Manage user home settings

```
posthog-pp-cli user-home-settings partial-update
```
— Update the authenticated user's pinned sidebar tabs and/or homepage for the current team. Pass
```
@me
```
as the UUID....
```
posthog-pp-cli user-home-settings retrieve
```
— Get the authenticated user's pinned sidebar tabs and configured homepage for the current team. Pass
```
@me
```
as the UUID.

users — Manage users

posthog-pp-cli users cancel-email-change-request-partial-update

— Cancel email change request partial update

```
posthog-pp-cli users destroy
```
— Destroy
```
posthog-pp-cli users list
```
— List
```
posthog-pp-cli users partial-update
```
— Update one or more of the authenticated user's profile fields or settings.

posthog-pp-cli users request-email-verification-create

— Request email verification create

```
posthog-pp-cli users retrieve
```
— Retrieve a user's profile and settings. Pass
```
@me
```
as the UUID to fetch the authenticated user; non-staff callers...
```
posthog-pp-cli users update
```
— Replace the authenticated user's profile and settings. Pass
```
@me
```
as the UUID to update the authenticated user....

posthog-pp-cli users verify-email-create

— Verify email create

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

— 创建邮箱验证

Finding the right command

查找合适的命令

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

bash

posthog-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

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

which

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

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

表示没有置信匹配项——请回退到

--help

或使用更精确的查询。

Recipes

使用示例

Find flags safe to archive

查找可安全归档的标志

bash

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

List flag keys with no evaluation events in 60 days — safe cleanup candidates

bash

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

列出60天内无评估事件的标志键——这些是安全的清理候选

Pre-ramp safety check

放量前安全检查

bash

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

Check error rate and purchase metric delta for flag-exposed users before ramping to 100%

bash

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

在放量至100%前，检查标志曝光用户的错误率和购买指标变化

Weekly experiment briefing

每周实验简报

bash

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

Cross-experiment pre-check summary for Monday standup — surface experiments needing traffic adjustment

bash

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

周一站会的跨实验预检查摘要——识别需要调整流量的实验

LLM cost by flag variant

按标志变体统计LLM成本

bash

posthog-pp-cli llm cost-attribution --flag model-tier --days 30 --agent --select variant,total_cost_usd,avg_cost_per_call

Compare LLM spend across A/B variants to decide if GPT-4o outperforms GPT-4o-mini in your context

bash

posthog-pp-cli llm cost-attribution --flag model-tier --days 30 --agent --select variant,total_cost_usd,avg_cost_per_call

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

Dashboard audit before all-hands

全员会议前仪表盘审计

bash

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

Surface dashboards with broken filters or stale data before a stakeholder presentation

bash

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

在利益相关者演示前，识别存在损坏过滤器或stale数据的仪表盘

Auth Setup

认证设置

Uses your PostHog personal API key (phx_...). Set POSTHOG_API_KEY or run

posthog-pp-cli auth set-token

. Supports both US (app.posthog.com) and EU (eu.posthog.com) instances via POSTHOG_HOST.

Run

posthog-pp-cli doctor

to verify setup.

使用您的PostHog个人API密钥（phx_...）。设置POSTHOG_API_KEY环境变量或执行

posthog-pp-cli auth set-token

。通过POSTHOG_HOST支持美国（app.posthog.com）和欧盟（eu.posthog.com）实例。

执行

posthog-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
```
posthog-pp-cli flags stale --agent --select key,days_stale
```
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
Explicit retries — use
```
--idempotent
```
only when an already-existing create should count as success, and
```
--ignore-missing
```
only when a missing delete target should count as success

在任何命令后添加

--agent

参数。等效于：

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

。

可管道传输 — 标准输出为JSON，错误输出到标准错误
可过滤 —
```
--select
```
参数保留字段子集。点路径可深入嵌套结构；数组可遍历元素。对于冗长的API，此参数对缩小上下文至关重要：
bash
```
posthog-pp-cli flags stale --agent --select key,days_stale
```
可预览 —
```
--dry-run
```
显示请求但不发送
离线友好 — 同步/搜索命令在可用时可使用本地SQLite存储
非交互式 — 从不提示，所有输入均通过标志传递
显式重试 — 仅当已存在的创建操作应被视为成功时使用
```
--idempotent
```
，仅当缺失的删除目标应被视为成功时使用
```
--ignore-missing
```

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:

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

Entries are stored locally at

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

. They are never POSTed unless

POSTHOG_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

POSTHOG_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存在问题时，可记录反馈：

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报告。简短、具体、单句：这样的反馈才更有价值。

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>

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

Sink	效果
`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.

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

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”模式。

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在运行时发现它们。

Exit Codes

退出码

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

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

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
→ show
```
posthog-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
→ 显示
```
posthog-pp-cli --help
```
输出
以
install
开头 → 如果以
```
mcp
```
结尾 → MCP安装；否则 → 参见顶部的前置条件
其他情况 → 直接使用（添加
```
--agent
```
参数执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:

bash

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

Verify:

claude mcp list

从此CLI已发布的public-library条目或预构建版本安装MCP二进制文件，然后注册：

bash

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

验证安装：

claude mcp list

Direct Use

直接使用

Check if installed:
```
which posthog-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

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

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

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

添加

--agent

参数执行命令：

bash

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

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