pp-dub

Dub — Printing Press CLI

前置条件：安装 CLI

此 Skill 由 dub-pp-cli 二进制文件驱动。**调用此 Skill 中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

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

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

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

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

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

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

何时使用此 CLI

当 Agent 或操作者需要在工作区范围内管理 Dub 时，请使用 dub-pp-cli，例如批量链接操作、全系列活动的 UTM 重写、合作伙伴计划审计、赏金分类处理，或本地跨资源分析。CLI 的本地 SQLite 存储使链接、分析数据、合作伙伴、佣金和赏金之间的联接既快速又可离线进行。若需要的不只是缩短链接或配置工作区，请优先使用 dub-pp-cli，而不是官方的 dub-cli。

独特功能

此 API 的其他工具均不具备这些功能。

可不断积累的本地状态

• links stale — 在工作区中查找已归档、已过期或零流量的链接，避免问题不断累积。

  在作品集评审或批量归档前，可用此功能清理不活跃的短链接。/analytics 端点无法通过单次调用筛选出“N 天内没有点击”的链接。

  dub-pp-cli links stale --days 90 --json --select id,key,clicks,archived
  

• links drift — 检测点击率环比下降超过指定阈值的链接。

  在报告截止日期前发现表现下滑的活动。可在每周自动化任务中使用，以找出悄然停止转化的归因链接。

  dub-pp-cli links drift --window 7d --threshold 30 --json
  

• links duplicates — 查找工作区中所有指向相同目标 URL 的链接。

  找出批量创建超量导致的意外重复项，以及迁移后可整合的链接。

  dub-pp-cli links duplicates --json
  

• links lint — 检查短链接键别名是否存在易混淆的冲突、保留字违规和品牌冲突风险。

  品牌活动上线前，可用此功能发现可能令合作伙伴困惑或触发保留字规则的相似别名。

  dub-pp-cli links lint --json
  

• links rollup — 按标签或文件夹汇总的性能仪表板，展示每个标签下所有链接的点击、潜在客户和销售数据。

  无需协调 5 个单独的 API 调用，即可比较不同标签维度的活动表现。

  dub-pp-cli links rollup --by clicks --group-by tag --json
  

• funnel — 按链接或活动统计从点击到潜在客户再到销售的转化率。

  找出潜在客户在归因漏斗中流失的环节。季度报告前，可用此功能发现点击量高但转化率低的链接。

  dub-pp-cli funnel --link mylink --min-clicks 50 --json
  

• customers journey — 在一个时间线中查看某位客户点击过的所有链接、成为潜在客户的时间，以及完成购买的时间。

  可用于类似 QBR 的客户审查，或排查特定客户的归因问题。

  dub-pp-cli customers journey cust_abc123 --json
  

面向 Agent 的基础设施

• links rewrite — 显示所有将发生变更的链接及确切补丁，然后再发送。

  在任何全局推广的重写操作前使用此命令。差异预览可避免最严重的一类批量修改错误。

  dub-pp-cli links rewrite --match 'utm_source=oldcampaign' --replace 'utm_source=newcampaign' --dry-run
  

• health — 跨资源的周一晨报：速率限制余量、已过期但仍有效的链接、失效的目标 URL、未经验证的域名、休眠标签、待审核的赏金提交。

  每天早上首先使用此命令，或将其用作 CI 探针。无需在各个仪表板之间切换，即可了解需要关注的事项。

  dub-pp-cli health --json
  

• since — 过去 N 小时内发生了什么？包括创建、更新、删除的链接，以及合作伙伴审批、新的赏金提交和点击量最高的实体。

  在 Agent 循环中使用此命令，总结自上次检查以来的工作区活动。成本低且幂等。

  dub-pp-cli since 24h --json
  

合作伙伴运营

• partners leaderboard — 按赚取的佣金、转化率和产生的点击量对合作伙伴排名。

  在评审合作伙伴等级前，用此命令找出表现最佳的合作伙伴；也可找出值得停用的休眠合作伙伴。

  dub-pp-cli partners leaderboard --by commission --top 10 --json
  

• partners audit-commissions — 对账合作伙伴、佣金、赏金和付款，标记过时的费率、遗漏的付款，以及仍在产生收益的已过期赏金。

  在付款周期前运行此命令，以发现意外的账单问题。在 CI 中进行任何佣金费率迁移前使用。

  dub-pp-cli partners audit-commissions --json
  

• bounties triage — 按状态、时长和赏金类型对合作伙伴提交的赏金证明进行分组。显示待审核的积压项目。

  每周运行此命令，避免赏金提交长期积压。提交长期未审核会削弱合作伙伴对赏金计划的信任。

  dub-pp-cli bounties triage --status pending --older-than 7d --json
  

• bounties payout-projection — 根据已批准但尚未付款的提交数量和当前佣金费率，预测即将产生的付款。

  用于财务和营销规划。在下一个付款周期前了解即将产生的付款负债。

  dub-pp-cli bounties payout-projection --window 30d --json
  

命令参考

bounties — 管理赏金

commissions — 管理佣金

• dub-pp-cli commissions bulk-update — 批量更新状态相同的佣金，最多 100 项。
• dub-pp-cli commissions list — 获取合作伙伴计划中佣金的分页列表。
• dub-pp-cli commissions update — 更新现有佣金金额。适用于处理退款（部分或全额）或欺诈性销售。

customers — 管理客户

• dub-pp-cli customers delete — 从工作区删除客户。
• dub-pp-cli customers get — 获取已通过身份验证的工作区中客户的分页列表。
• dub-pp-cli customers get-id — 根据 ID 获取已通过身份验证的工作区中的客户。若要根据外部 ID 获取客户，请在 ID 前添加...
• dub-pp-cli customers update — 更新工作区中的客户。

domains — 管理域名

• dub-pp-cli domains check-status — 检查域名是否可供购买。可一次检查多个域名。
• dub-pp-cli domains create — 为已通过身份验证的工作区创建域名。
• dub-pp-cli domains delete — 从工作区删除域名。此操作无法撤销，还会删除与该域名关联的所有链接。
• dub-pp-cli domains list — 获取已通过身份验证的工作区中域名的分页列表。
• dub-pp-cli domains register — 为已通过身份验证的工作区注册域名。仅限企业版计划使用。
• dub-pp-cli domains update — 更新已通过身份验证的工作区中的域名。

dub-analytics — 管理 dub 分析

• dub-pp-cli dub-analytics — 获取链接、域名或已通过身份验证的工作区的分析数据。响应类型取决于 event...

events — 管理事件

• dub-pp-cli events — 获取已通过身份验证的工作区中事件的分页列表。

folders — 管理文件夹

• dub-pp-cli folders create — 为已认证的工作区创建文件夹。
• dub-pp-cli folders delete — 从工作区删除文件夹。所有现有链接仍可使用，但将不再与……关联。
• dub-pp-cli folders list — 获取已认证工作区的分页文件夹列表。
• dub-pp-cli folders update — 更新工作区中的文件夹。

links — 管理链接

• dub-pp-cli links bulk-create — 为已认证的工作区批量创建最多 100 个链接。
• dub-pp-cli links bulk-delete — 为已认证的工作区批量删除最多 100 个链接。
• dub-pp-cli links bulk-update — 为已认证的工作区使用相同数据批量更新最多 100 个链接。
• dub-pp-cli links create — 为已认证的工作区创建链接。
• dub-pp-cli links delete — 删除已认证工作区的链接。
• dub-pp-cli links get — 获取已认证工作区的分页链接列表。
• dub-pp-cli links get-count — 获取已认证工作区的链接数量。
• dub-pp-cli links get-info — 获取链接信息。
• dub-pp-cli links update — 更新已认证工作区的链接。如果没有更改，则原样返回。
• dub-pp-cli links upsert — 根据 URL 为已认证的工作区插入或更新链接。如果已存在 URL 相同的链接，则返回该链接（或……

partners — 管理合作伙伴

• dub-pp-cli partners approve — 批准提交给你的计划的待处理合作伙伴申请。该合作伙伴将加入指定的群组，并……
• dub-pp-cli partners ban — 禁止合作伙伴加入你的计划。这会停用其所有链接，并将所有佣金标记为已取消。
• dub-pp-cli partners create — 创建或更新合作伙伴记录（插入或更新行为）。如果已存在电子邮件相同的合作伙伴，其……
• dub-pp-cli partners create-link — 为已加入你计划的合作伙伴创建链接。
• dub-pp-cli partners deactivate — 停用你计划中的合作伙伴，并停用其所有有效链接。其佣金和付款……
• dub-pp-cli partners list — 列出合作伙伴计划中的所有合作伙伴。
• dub-pp-cli partners list-applications — 获取合作伙伴计划待处理申请的分页列表。
• dub-pp-cli partners reject — 拒绝提交给你的计划的待处理合作伙伴申请。系统会通过电子邮件通知该合作伙伴，其申请……
• dub-pp-cli partners retrieve-analytics — 获取计划中某个合作伙伴的分析数据。响应类型因 groupBy 查询参数而异。
• dub-pp-cli partners retrieve-links — 根据合作伙伴 ID 或租户 ID 获取合作伙伴的链接。
• dub-pp-cli partners upsert-link — 为已加入你计划的合作伙伴插入或更新链接。如果已存在 URL 相同的链接，则返回该链接……

payouts — 管理付款

• dub-pp-cli payouts — 获取合作伙伴计划付款的分页列表。

qr — 管理二维码

• dub-pp-cli qr — 获取链接的二维码。

tags — 管理标签

• dub-pp-cli tags create — 为已认证的工作区创建标签。
• dub-pp-cli tags delete — 从工作区删除标签。所有现有链接仍可使用，但将不再与此……关联。
• dub-pp-cli tags get — 获取已认证工作区的分页标签列表。
• dub-pp-cli tags update — 更新工作区中的标签。

tokens — 管理令牌

• dub-pp-cli tokens — 为指定的合作伙伴/租户创建推荐嵌入令牌。此端点会首先尝试查找现有……

track — 管理跟踪

• dub-pp-cli track lead — 跟踪短链接的潜在客户。
• dub-pp-cli track open — 此端点用于跟踪用户通过 Dub 提供的深层链接打开应用的情况（适用于 iOS 和 Android）。
• dub-pp-cli track sale — 跟踪短链接的销售。

查找合适的命令

当你知道想做什么，却不知道该用哪个命令时，直接询问 CLI：

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

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有足够确定的匹配项，此时请改用 --help 或缩小查询范围。

使用示例

找出值得归档的休眠链接

dub-pp-cli sync && dub-pp-cli links stale --days 60 --json --select key,url,clicks,createdAt

先同步，然后查询过去 60 天内点击次数为零的链接。通过管道传递给 jq，进一步筛选或创建归档批次。

发送前预览全营销活动的 UTM 替换

dub-pp-cli links rewrite --match 'utm_source=launch' --replace 'utm_source=summer' --dry-run --json

差异预览会显示所有将发生变化的链接。阅读补丁后再移除 --dry-run。

梳理等待超过 7 天的赏金提交

dub-pp-cli bounties triage --status pending --older-than 7d --json --select id,partnerId,bountyType,submittedAt

列出积压在队列中的合作伙伴提交。通过管道传递给 jq，按 partnerId 分组以生成联系名单。

排名前 10 的合作伙伴各自的 ROI

dub-pp-cli partners leaderboard --by commission --top 10 --agent --select 'partnerId,partnerName,clicks,leads,sales,commission'

将 /partners/analytics 与本地佣金和付款数据合并。使用带点分隔路径的 --select，缩小响应内容以便 Agent 处理；排行榜默认会返回较宽的行。

同步，然后运行完整的周一早间健康检查

dub-pp-cli sync && dub-pp-cli health --json

汇总报告包括速率限制余量、已过期但仍处于活动状态的链接、失效的目标 URL、未经验证的域名，以及等待审核的赏金提交。

身份验证设置

dub-pp-cli 从环境变量 DUB_API_KEY 中读取密钥（遵循 Speakeasy 约定；也接受 DUB_TOKEN，以兼容之前的社区 CLI）。密钥的作用范围限定于工作区，工作区由密钥隐式指定。前往 dub.co/settings/tokens 获取密钥，然后运行 dub-pp-cli doctor 验证连接。

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

Agent 模式

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

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

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

  dub-pp-cli commissions list --agent --select id,name,status
  

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

• 便于离线使用 — 有本地 SQLite 存储时，同步和搜索命令可以使用该存储

• 非交互式 — 从不显示提示，每项输入都必须通过标志传入

响应封装结构

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

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

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

Agent 反馈

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

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

条目会保存在本地 ~/.dub-pp-cli/feedback.jsonl。只有设置了 DUB_FEEDBACK_ENDPOINT，且传入了 --send 或设置了 DUB_FEEDBACK_AUTO_SEND=true 时，条目才会通过 POST 发送。默认情况下，反馈仅保存在本地。

写下让你感到意外的地方，而不是提交 Bug 报告。简短、具体、一行即可：这才是能积少成多的部分。

输出传递

每条命令都接受 --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”模式。

dub-pp-cli profile save briefing --json
dub-pp-cli --profile briefing commissions list
dub-pp-cli profile list --json
dub-pp-cli profile show briefing
dub-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

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

2. 在 Claude Code 中注册：

   claude mcp add dub-pp-mcp -- dub-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

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

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