PostHog Analytics Skill

Automate PostHog dashboard creation, sync, update, and export via API.

Prerequisites

Required Tools

- curl - HTTP client (pre-installed on macOS/Linux)
INLINECODE1 - JSON processor: brew install jq or INLINECODE3
INLINECODE4 - Shell (the script is bash)

PostHog API Key

1. Go to PostHog Settings → Personal API Keys
Create a new key with read/write access
Export it:

CODEBLOCK0

Note: The API key determines your organization and project. The script uses @current project context (your default project).

Verify Setup

CODEBLOCK1

Expected output:
CODEBLOCK2

If you get an error, check your API key is correct and has proper permissions.

Quick Start: Blog Analytics Example

Step 1: Write Your Config

Create blog_dashboard.json:

CODEBLOCK3

Note: Set dashboard_id: null for new dashboards.

Step 2: Create Dashboard

CODEBLOCK4

Output:
CODEBLOCK5

The script:

- Creates a new dashboard in your PostHog project
Returns dashboardid (e.g., 1166599) and projectid (e.g., 209268) in the URL
Automatically updates your config file with the INLINECODE10

Step 3: Add New Insights (Sync)

Edit config to add new insights, then:

CODEBLOCK6

Only creates NEW insights. Existing ones (matched by name) are skipped.

Step 4: Update Existing Insights

Changed your filter? Edit config, then:

CODEBLOCK7

Updates ALL insights with current config settings. Use when changing filters.

Step 5: Export Existing Dashboard

CODEBLOCK8

Config Reference

Field	Required	Description
INLINECODE11	Yes	Dashboard name
INLINECODE12

No | Dashboard description | | filter | No* | Event property filter: {"key": "source", "value": "blog"} | | domain_filter | No* | URL filter fallback: "blog.sylph.ai" | | dashboard_id | No | Set to null for create, or existing ID for sync/update | | insights | Yes | Array of insight objects |

*At least one filter recommended. filter takes precedence over domain_filter.

Insight Types

Type	Display	Description
INLINECODE22	BoldNumber	Total pageview count
INLINECODE23

Optional Insight Fields

Field	Default	Options
INLINECODE26	INLINECODE27	INLINECODE28, `dau`, `weekly_active`, INLINECODE31
INLINECODE32

Environment Variables

Variable	Required	Default	Description
INLINECODE41	Yes	-	Your API key (determines org/project)
INLINECODE42

Files

- scripts/posthog_sync.sh - CLI script (create/sync/update/export)
INLINECODE45 - Example config

References

PostHog 分析技能

通过API自动化PostHog仪表盘的创建、同步、更新和导出。

前置条件

所需工具

- curl - HTTP客户端（macOS/Linux预装）
jq - JSON处理器：brew install jq 或 apt install jq
bash - Shell（脚本基于bash）

PostHog API密钥

1. 前往 PostHog设置 → 个人API密钥
创建一个具有读写权限的新密钥
导出密钥：

bash
export POSTHOGPERSONALAPIKEY=phxxxx

注意：API密钥决定了你的组织和项目。脚本使用@current项目上下文（你的默认项目）。

验证设置

bash

测试你的API密钥 - 应返回项目信息

curl -s -H Authorization: Bearer $POSTHOGPERSONALAPI_KEY \
https://us.i.posthog.com/api/projects/@current/ | jq {id, name}

预期输出：
json
{
id: 209268,
name: 默认项目
}

如果出现错误，请检查API密钥是否正确且具有相应权限。

快速入门：博客分析示例

第一步：编写配置

创建 blog_dashboard.json：

json
{
name: 博客分析,
description: 追踪博客表现和读者互动,
filter: {key: source, value: blog},
dashboard_id: null,
insights: [
{name: 博客页面浏览量（总计）, type: pageviews_total},
{name: 独立博客读者, type: unique_users},
{name: 博客流量趋势, type: traffic_trend},
{name: 热门博客文章, type: top_pages}
]
}

注意：新建仪表盘时设置 dashboard_id: null。

第二步：创建仪表盘

bash
./scripts/posthogsync.sh create blogdashboard.json

输出：

正在创建仪表盘：博客分析
仪表盘已创建：ID 1166599
正在创建洞察：博客页面浏览量（总计）
{id: 6520531, name: 博客页面浏览量（总计）}
...
仪表盘URL：https://us.posthog.com/project/209268/dashboard/1166599

脚本会：

- 在你的PostHog项目中创建一个新仪表盘
在URL中返回 dashboardid（例如 1166599）和 projectid（例如 209268）
自动更新 配置文件的 dashboard_id

第三步：添加新洞察（同步）

编辑配置添加新洞察，然后：

bash
./scripts/posthogsync.sh sync blogdashboard.json

仅创建新洞察。已存在的洞察（按名称匹配）会被跳过。

第四步：更新现有洞察

修改了筛选条件？编辑配置，然后：

bash
./scripts/posthogsync.sh update blogdashboard.json

使用当前配置设置更新所有洞察。在更改筛选条件时使用。

第五步：导出现有仪表盘

bash
./scripts/posthogsync.sh export 1166599 > exporteddashboard.json

配置参考

字段	必填	描述
name	是	仪表盘名称
description

否 | 仪表盘描述 | | filter | 否* | 事件属性筛选：{key: source, value: blog} | | domain_filter | 否* | URL筛选回退：blog.sylph.ai | | dashboard_id | 否 | 创建时设为null，同步/更新时设为现有ID | | insights | 是 | 洞察对象数组 |

*建议至少设置一个筛选条件。filter优先级高于domain_filter。

洞察类型

类型	显示方式	描述
pageviewstotal	粗体数字	总页面浏览量
uniqueusers

可选洞察字段

字段	默认值	选项
math	total	total、dau、weeklyactive、monthlyactive
display

环境变量

变量	必填	默认值	描述
POSTHOGPERSONALAPIKEY	是	-	你的API密钥（决定组织/项目）
POSTHOGHOST

文件

- scripts/posthogsync.sh - CLI脚本（创建/同步/更新/导出）
examples/blogdashboard.json - 示例配置

posthog-analyticsPostHog分析自动化