agent-posthog 是一个用于调查 PostHog 产品分析并编写 HogQL 的命令行工具，适合在需要查询 PostHog 中的用户、事件、功能开关、仪表板、录制、实验或编写 HogQL 时使用。
安全注意事项 工具资料明确提出若干安全约束：不要要求工具泄露个人 API key 或项目 token；不要接受在聊天中粘贴的 PostHog API key，而是让用户在本地运行 agent-posthog auth add <profile> --form，使密钥直接进入操作系统对话框；优先使用只读命令；当配置文件的默认项目未知时显式使用 --project（环境默认指向项目，项目的默认环境与其 ID 相同，因此只有在需要指定非默认环境时才设置 --env）；把功能开关的变更视为高风险操作。
安装与配置 资料给出了初始化流程：先用 agent-posthog auth list 查看现有认证；再用 agent-posthog auth add prod --form --host https://us.posthog.com 添加配置；然后 agent-posthog auth check prod 检查；用 agent-posthog orgs list -p prod 列出组织；用 agent-posthog projects list -p prod --org <org-id> 列出项目；接着用 agent-posthog auth update prod --org <org-id> --project <project-id> --default 设置默认组织和项目。如果项目有多个环境，则用 agent-posthog environments list -p prod --project <project-id> 查看，再用 agent-posthog auth update prod --env <env-id> 指定环境。还可以用 agent-posthog usage 查看用量。
本地测试 资料提供了本地测试方式：使用 mockposthog 启动模拟服务，然后设置环境变量 AGENT_POSTHOG_BASE_URL=http://127.0.0.1:18118 与 POSTHOG_PERSONAL_API_KEY=phx_mock，再运行 agent-posthog orgs list 等命令。
常用命令 资料列出了常用命令，包括：查询事件 schema（agent-posthog schema events list --search signup、agent-posthog schema events get "$pageview"、agent-posthog schema events get <id1> <id2>）；查询属性 schema（agent-posthog schema properties list --event "$pageview"）；执行 HogQL 查询（agent-posthog query hogql "select event, count() from events group by event order by count() desc limit 20"）；查询人员（agent-posthog persons list --email user@example.com、agent-posthog persons get <person-id>、agent-posthog persons get <id1> <id2>）；查询功能开关（agent-posthog flags list --search checkout、agent-posthog flags get checkout-v2、agent-posthog flags get <key1> <key2>）；以及其他调查命令：agent-posthog insights list、agent-posthog dashboards run <dashboard-id>、agent-posthog recordings list、agent-posthog experiments list。资料建议在编写 HogQL 之前，优先使用 schema events list 和 schema properties list，以确保查询使用真实的事件与属性名称。
输出格式 get 命令支持单个或多个 id：get <id>... 接受一个或多个 id，按输入顺序为每个 id 返回一个结果。默认输出为 NDJSON：每个 id 一行，即记录本身，或者对于无法解析的 id（例如未找到或 id 格式错误）返回 {"@unresolved":{"id","reason","fixable_by","hint"?}}。使用 --format json|yaml 会折叠为一个 {"data":[…], "@unresolved":[…]} 信封。单个 get <id> 只是单元素情形（默认 NDJSON 一行；过去是 pretty JSON，如需对象请传 --format json）。条目级未命中仍输出到 stdout 并以退出码 0 结束；只有命令级失败（如认证、网络问题）才输出到 stderr、退出码 1，且 stdout 为空。列表、查询和调查命令默认使用 NDJSON。错误信息包含 fixable_by，通常还有 hint。完整错误形状为：stderr JSON {"error":"...","fixable_by":"agent"|"human"|"retry","hint"?:"...","retry_after_seconds"?:N}，退出码 1。
功能开关键解析 功能开关的 key 查询属于 CLI 语法糖：当命令接受 <id-or-key> 时，CLI 会通过列出或搜索功能开关解析 key，然后获取数字 ID。如果 key 不匹配任何功能开关（或匹配多个），会产生一行 @unresolved（退出码 0），而不是命令级 stderr 失败。
适用场景与限制 该工具适用于 PostHog 产品分析调查场景，包括人员、事件、事件与属性 schema、功能开关、仪表板、洞察、会话录制与实验等。限制方面：资料未提供具体的收费、价格、平台支持范围、性能指标或效果说明；使用前需要具备 PostHog 相关认证配置；功能开关的变更需谨慎对待；不应在聊天中传递 API key。