pp-customer-io

Customer.io — Printing Press CLI

前提条件：安装 CLI

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

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

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

2. 验证：customer-io-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

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

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

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

何时使用此 CLI

当你需要在 Customer.io 中执行一些在 Web UI 中操作起来很繁琐的任务时，可以使用此 CLI：批量抑制并保留审计记录、按细分交叉分析旅程漏斗、用于事件分流的客户 360 时间线、高风险发送前的广播预检，或 Reverse-ETL 健康检查。如果 Agent 需要操作 Customer.io，它也是合适的工具——随附的 MCP 服务通过 stdio 和 HTTP 传输方式公开相同的动词。对于原始事件摄取（Track API）或按来源划分的 CDP 写入密钥，建议使用官方服务端 SDK。

独特功能

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

不断积累的本地状态

• campaigns funnel — 呈现单个活动的逐步旅程漏斗（已发送 → 已送达 → 已打开 → 已点击 → 已转化），还可选择按细分交叉分析。

  当 Agent 被问到“细分 X 中有多少人完成了旅程 Y”时，使用此功能——只需针对已同步的数据查询一次，无需导出两次再使用电子表格。

  customer-io campaigns funnel cmp_482 --segment seg_19 --since 30d --json
  

• segments overlap — 根据本地存储计算细分成员关系的两两及多方维恩图。

  用于验证受众设计——例如，无需导出两次，即可检查“流失风险细分和高价值细分是否重叠？”。

  customer-io segments overlap seg_19 seg_42 seg_88 --json
  

• customers timeline — 按时间顺序展示每位客户的事件流，合并本地存储中的身份识别、投递、抑制和细分成员关系事件。

  用于事件分流，或查询“这位用户收到欢迎短信了吗？”——运行一条命令即可，不必在 UI 中翻找半天。

  customer-io customers timeline [email protected] --since 30d --json
  

发送安全性

• broadcasts preflight — 触发广播之前，检查目标细分规模、抑制重叠情况，以及本地投递缓存中的最近发送时间；输出包含结构化原因的绿/黄/红判定。

  在发送任何广播前使用，避免重复发送、意外过量发送或 429 风暴。

  customer-io broadcasts preflight 123457 bcr_77 --segment seg_19 --json
  

• suppressions audit — 将某个时间窗口内的每次抑制归因于触发该抑制的退信或投诉投递（如果之前没有相关事件，则标记为“manual”）。

  当运维工程师需要说明某位客户为何被抑制，或审计由投诉导致的流失时使用。

  customer-io suppressions audit --since 30d --reason bounce --json
  

• cdp-reverse-etl health — 以具名动词查询 Reverse-ETL 运行历史，查看状态、行数、错误原因，并可选用 --watch 轮询模式。

  用于每天站会时回答“数据仓库同步是否正常？”——可取代三条单独的 API 调用和对应的 jq 过滤器。

  customer-io cdp-reverse-etl health --since 24h --watch
  

审计与溯源

• suppressions bulk add — 读取包含电子邮箱/客户 ID 的 CSV 或 JSONL 文件，通过自适应限流分发真实的抑制调用，并将每次调用追加到按日期归档的本地 JSONL 审计日志中。

  适用于受合规要求驱动的批量操作，方便日后说明“何时、由谁、以什么状态码抑制了哪些对象”。

  customer-io suppressions bulk add --from-csv complaints.csv --reason complaint --dry-run
  

• deliveries triage — 按模板、状态和时间范围筛选实时及本地投递记录，并生成可独立使用的资料包（包含按错误原因分组的 SQL 查询结果摘要 summary.md、deliveries.jsonl 和 recipients.txt），可直接粘贴到事件文档中。

  将资料包交给 Claude 或放入 Notion 文档，即可一次性交接事件；无需再花 30 多分钟滚动浏览 UI。

  customer-io deliveries triage --template tx_91 --status bounced --since 1h --bundle ./incident-2026-05-07
  

命令参考

broadcasts — 列出、查看并触发单次广播（每 10 秒限 1 个请求）

• customer-io-pp-cli broadcasts get — 获取一条广播
• customer-io-pp-cli broadcasts list — 列出某个环境中的广播
• customer-io-pp-cli broadcasts metrics — 读取一条广播的指标
• customer-io-pp-cli broadcasts trigger — 触发一条广播（每 10 秒限 1 个请求）

campaigns — 列出营销活动并读取营销活动和旅程指标

• customer-io-pp-cli campaigns get — 获取一项营销活动
• customer-io-pp-cli campaigns journey_metrics — 读取逐步旅程漏斗指标
• customer-io-pp-cli campaigns list — 列出某个环境中的营销活动
• customer-io-pp-cli campaigns metrics — 读取某项营销活动的汇总指标

cdp_destinations — 列出 CDP 目标（Premium 功能）

• customer-io-pp-cli cdp_destinations — 列出 CDP 目标

cdp_reverse_etl — 列出 Reverse-ETL 同步（Premium 功能）

• customer-io-pp-cli cdp_reverse_etl — 列出 Reverse-ETL 同步

cdp_sources — 列出 CDP 数据源（Premium 功能）

• customer-io-pp-cli cdp_sources — 列出 CDP 源

customers — 管理某个环境（工作区）中的 Customer.io 客户资料

• customer-io-pp-cli customers get — 获取客户的属性
• customer-io-pp-cli customers list_activities — 列出客户的活动事件
• customer-io-pp-cli customers list_messages — 列出发送给客户的消息
• customer-io-pp-cli customers list_segments — 列出客户所属的细分

deliveries — 检查投递事件（发送、打开、点击、退信、投诉）

• customer-io-pp-cli deliveries get — 获取一条投递记录
• customer-io-pp-cli deliveries list — 列出近期投递记录

exports — 启动、监控并下载数据导出（细分成员、投递记录、客户等）

• customer-io-pp-cli exports download — 获取已完成导出的签名下载 URL
• customer-io-pp-cli exports get — 获取导出的状态
• customer-io-pp-cli exports list — 列出近期导出

segments — 列出细分并检查细分成员

• customer-io-pp-cli segments customer_count — 获取某个细分中的客户数量
• customer-io-pp-cli segments get — 获取一个细分
• customer-io-pp-cli segments list — 列出某个环境中的细分
• customer-io-pp-cli segments members — 列出某个细分中的客户 ID

suppressions — 抑制和取消抑制客户；这是合规操作的官方审计界面

• customer-io-pp-cli suppressions add — 抑制一位客户
• customer-io-pp-cli suppressions count — 获取某个环境中被抑制的客户数量（Customer.io 没有列表端点；请使用 'exports...
• customer-io-pp-cli suppressions remove — 移除一项抑制

transactional — 检查事务性模板和指标

• customer-io-pp-cli transactional get_template — 获取一个事务性模板
• customer-io-pp-cli transactional list_templates — 列出事务性模板
• customer-io-pp-cli transactional template_metrics — 读取一个事务性模板的指标

webhooks — 管理用于投递和互动事件的 Reporting Webhooks

• customer-io-pp-cli webhooks get — 获取一个 Reporting Webhook
• customer-io-pp-cli webhooks list — 列出 Reporting Webhooks

workspaces — 列出 Service Account 可见的环境（工作区）

• customer-io-pp-cli workspaces account — 获取当前账户详情
• customer-io-pp-cli workspaces list — 读取当前账户信息，包括 SA 令牌可见的 environment_ids

查找合适的命令

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

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

which 会在此 CLI 精选的功能索引中，将自然语言能力查询匹配到最合适的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help 或缩小查询范围。

使用示例

查找尚未参与欢迎工作流的高价值客户

customer-io campaigns funnel cmp_welcome --segment seg_high_value --since 90d --agent --select steps.delivered.count,steps.opened.count,steps.clicked.count,non_engaged.recipients

funnel 命令会将同步的投递记录与细分受众成员关联起来；--agent + --select 会从层级较深的漏斗响应中筛选出计数和未参与的收件人列表，让 Agent 的上下文保持精简。

为交易邮件退信激增事件整理事件资料包

customer-io deliveries triage --template tx_password_reset --status bounced --since 2h --bundle ./incident-bounce-2026-05-07

生成包含错误原因分组的 summary.md、包含完整投递对象的 deliveries.jsonl，以及 recipients.txt，可直接粘贴到 Notion 事件文档或 Claude 摘要提示词中。

验证群发是否可以安全触发

customer-io broadcasts preflight bcr_summer_promo --segment seg_active_30d --json

返回绿／黄／红判定及结构化原因（细分受众规模、抑制名单重叠情况、基于同步投递记录的上次发送时间）。每次进行规模较大的群发前都应运行。

批量抑制投诉名单并保留来源记录

customer-io suppressions bulk add --from-csv complaints-2026-05.csv --reason complaint --dry-run

去掉 --dry-run 即可提交。每次调用都会写入 ~/.customer-io/audit/suppressions-2026-05-07.jsonl，记录时间戳、收件人、状态和 HTTP 状态码，以便日后核查。

实时监控 Reverse-ETL 同步

customer-io cdp-reverse-etl health --watch --since 24h

每隔 60 秒轮询一次，并为每次同步打印一行状态；通过管道传给 tee 即可保存日志。

身份验证设置

Customer.io 使用服务账号令牌（前缀为 sa_live_*）。CLI 会通过 OAuth 客户端凭据端点 https://us.fly.customer.io/v1/service_accounts/oauth/token（欧盟工作区使用 eu.fly.customer.io），将令牌换成短期 JWT，并将该 JWT 用作 Journeys UI API（/v1/...）和 CDP 控制平面（/cdp/api/...）的 Bearer 令牌。运行一次 customer-io auth login --sa-token $CIO_TOKEN --region us；缓存的 JWT 会自动刷新。Track API（使用独立的 Site ID + API Key 身份验证）有意不纳入 v1 范围——SA 令牌是统一凭据。

运行 customer-io-pp-cli doctor 以验证设置。

Agent 模式

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

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

• 支持筛选 — --select 可保留部分字段。带点路径可深入嵌套结构；数组会逐个遍历元素。对于冗长的 API，这对缩小上下文至关重要：

  customer-io-pp-cli broadcasts list mock-value --agent --select id,name,status
  

• 支持预览 — --dry-run 显示请求而不发送

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

• 非交互式 — 不会提示输入；所有输入都通过标志指定

• 显式重试 — 仅当已存在的创建操作应视为成功时，才使用 --idempotent

响应封装

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

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

从 .results 解析数据，并查看 .meta.source 以判断数据来自实时来源还是本地来源。只有当 stdout 连接到终端时，才会向 stderr 打印人类可读的 N results (live) 摘要；通过管道处理或由 Agent 使用时，stdout 只会输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

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

条目会保存在本地的 ~/.customer-io-pp-cli/feedback.jsonl 中。除非设置了 CUSTOMER_IO_FEEDBACK_ENDPOINT，且传入了 --send 或设置了 CUSTOMER_IO_FEEDBACK_AUTO_SEND=true，否则不会发送 POST 请求。默认情况下，反馈仅保存在本地。

写下让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这些反馈会逐步累积，发挥更大作用。

输出交付

每个命令都接受 --deliver <sink>。输出会写入指定的目标位置，同时写入 stdout，或取代 stdout，这样 Agent 无需手动管道传输即可路由命令结果。支持三种目标位置：

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

遇到未知协议时会拒绝执行，并返回一条结构化错误，列出支持的协议。Webhook 请求失败时会返回非零状态，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

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

customer-io-pp-cli profile save briefing --json
customer-io-pp-cli --profile briefing broadcasts list mock-value
customer-io-pp-cli profile list --json
customer-io-pp-cli profile show briefing
customer-io-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/other/customer-io/cmd/customer-io-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add customer-io-pp-mcp -- customer-io-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

   customer-io-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，查看子命令帮助：customer-io-pp-cli <command> --help。