pp-gohighlevel

GoHighLevel — Printing Press CLI

前置条件：安装 CLI

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

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

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

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

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

go install github.com/mvanhorn/printing-press-library/library/sales-and-crm/gohighlevel/cmd/gohighlevel-pp-cli@latest

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

何时使用此 CLI

当你将 GoHighLevel 用作日常运营系统，尤其是需要跨多个子账户操作时，请使用此 CLI。它专为机构运营者和经纪公司主管打造，支持通过终端快速查找联系人、查看跨销售管道的漏斗、去重，以及对 CRM 数据执行类似 SQL 的查询。本地 SQLite 缓存使它特别适用于批量操作（为 5000 位联系人添加标签）、定期报告（周一 L10 准备工作）以及由 Agent 驱动的工作流；否则，这些操作都需要数十次 API 往返调用。

独特功能

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

会不断积累价值的本地状态

• opp stale — 查找在某个阶段停留超过 N 天的销售机会，使用同步历史推算阶段进入时间戳。

  当用户问“哪些招募对象在这个阶段停留太久了”时，这是唯一无需重新运行其自定义仪表板脚本就能解答的方法。

  gohighlevel-pp-cli opp stale --pipeline "Non-KW" --stage "Recruit Lead" --days 30 --json
  

• opp funnel — 按阶段统计销售管道中的数量和总金额，并以 TSV 格式输出，可直接粘贴到仪表板表格中。

  用一条命令替代用户的周一 L10 准备脚本；Agent 可按需使用不同的销售管道筛选条件重新运行。

  gohighlevel-pp-cli opp funnel --pipeline "Non-KW" --tsv
  

• sql — 对 contacts、opportunities、pipelines、stages、tags、custom_fields、conversations、messages 和 appointments 的本地 SQLite 镜像执行只读 SQL 查询。

  跨实体查询是其独特优势。Agent 想要了解的任何 GHL 数据，都可以通过一条 SQL 语句解答，而不必像以往那样用 Python 拼接三次分页 API 调用。

  gohighlevel-pp-cli sql "SELECT name, COUNT(*) FROM opportunities GROUP BY pipelineStageId ORDER BY 2 DESC" --json
  

• contact dedup — 按小写电子邮件地址和 E.164 电话号码对联系人分组，根据已填写字段数量和最近更新时间评分，并生成合并方案。

  取代运营者每周运行的 200 行 Python 脚本。Agent 可以在实际修改数据前预览合并方案。

  gohighlevel-pp-cli contact dedup --by email,phone --dry-run --json
  

• contact decay — 查找处于某个阶段且 N 天内没有收到或发送任何消息的销售机会。

  在招募对象流失前发现其逐渐失去联系的情况。运营者现有的提醒脚本可以简化为一条命令，Agent 也可使用不同的阈值重新运行。

  gohighlevel-pp-cli contact decay --stage "Engaged" --idle-days 30 --json
  

• recruit hot — 根据业绩信号、互动情况和招募标签数量的综合指标，对招募对象进行排名。

  在 Kymber 提出要求前，先做好周一 L10 准备。Agent 无需重新运行整个 Python 流程，即可调整阈值。

  gohighlevel-pp-cli recruit hot --threshold 25 --tsv
  

• convo thread — 从本地消息表中重建单个联系人的 SMS、电子邮件和通话时间线。

  在联系任何招募对象前，运营者都希望能集中查看完整对话。Agent 无需进行四次 MCP 调用，即可读取完整历史记录。

  gohighlevel-pp-cli convo thread --contact [email protected] --json
  

服务专属防护措施

• field id — 将人类可读的自定义字段名称转换为不透明的 GHL ID，并在拼写错误时提供“你是否想找”建议。

  将 field id 与 sql 配合使用，可根据自定义字段值查询联系人，无需硬编码 20 个字符的 GHL ID；从根本上杜绝重命名后失效这一类问题。

  gohighlevel-pp-cli field id "Agent Affiliation"
  

• config use — 为每个 GHL 子账户（KWCP、THINK）设置命名配置，并确保所有命令都遵循 --location 标志。

  避免误操作到错误租户。只需在会话开始时告诉 Agent“使用 kwcp 配置”，之后就不用再操心。

  gohighlevel-pp-cli config use kwcp && gohighlevel-pp-cli --location think opp funnel --pipeline "Non-KW"
  

• doctor — 验证 PIT 令牌（自动将前缀转换为小写）、ping 当前活动位置，并报告本地缓存状态。

  任何操作出现异常时，首先运行此命令。Agent 可在复杂流程之前调用它，快速排除令牌或缓存问题。

  gohighlevel-pp-cli doctor --json
  

面向 Agent 的基础设施

• contact bulk-tag — 为从标准输入读取的多个联系人添加或移除标签，分批次（每批 100 个）发送，并在连接中断时重试。

  这是任何代理机构日常工作中最具价值的操作：每次培训、每次营销活动、每次导入之后都会用到。没有它，操作人员每次都得手动编写重试逻辑。

  cat emails.csv | gohighlevel-pp-cli contact bulk-tag --tag "Attended_2026-05-19" --dry-run
  

HTTP 传输

此 CLI 使用兼容 Chrome 的 HTTP 传输来访问面向浏览器的端点。执行常规 API 调用时，无需常驻浏览器进程。

命令参考

calendars — 管理日历

• gohighlevel-pp-cli calendars create — 创建
• gohighlevel-pp-cli calendars create-appointment — 创建预约
• gohighlevel-pp-cli calendars delete-appointment — 删除预约
• gohighlevel-pp-cli calendars get — 获取
• gohighlevel-pp-cli calendars get-appointment — 获取预约
• gohighlevel-pp-cli calendars list — 列出
• gohighlevel-pp-cli calendars list-events — 列出某个位置的日历事件
• gohighlevel-pp-cli calendars update-appointment — 更新预约

contacts — 管理联系人

• gohighlevel-pp-cli contacts bulk-update-tags — 批量为多个联系人添加或移除标签
• gohighlevel-pp-cli contacts create — 创建联系人
• gohighlevel-pp-cli contacts delete — 删除联系人
• gohighlevel-pp-cli contacts find-duplicate — 按电子邮件或姓名查找重复联系人
• gohighlevel-pp-cli contacts get — 按 ID 获取联系人
• gohighlevel-pp-cli contacts search — GHL 的 /contacts/search 硬性限制为 100 页。请使用响应中返回的 startAfter 游标进行分页...
• gohighlevel-pp-cli contacts update — 更新联系人
• gohighlevel-pp-cli contacts upsert — 按电子邮件或电话创建或更新联系人

conversations — 管理对话

• gohighlevel-pp-cli conversations get — 获取
• gohighlevel-pp-cli conversations search — 搜索对话（版本 2021-04-15）
• gohighlevel-pp-cli conversations send-message — 发送 SMS、电子邮件或其他消息

locations — 管理位置

• gohighlevel-pp-cli locations get — 获取
• gohighlevel-pp-cli locations search — 搜索位置（代理机构级别）

opportunities — 管理商机

• gohighlevel-pp-cli opportunities create-opportunity — 创建商机
• gohighlevel-pp-cli opportunities delete-opportunity — 删除商机
• gohighlevel-pp-cli opportunities get-opportunity — 获取商机
• gohighlevel-pp-cli opportunities list-pipelines — 列出某个位置的销售管道
• gohighlevel-pp-cli opportunities search — 搜索某个销售管道中的商机
• gohighlevel-pp-cli opportunities update-opportunity — 更新商机
• gohighlevel-pp-cli opportunities upsert-opportunity — 创建或更新商机

surveys — 管理调查问卷

• gohighlevel-pp-cli surveys — 列出

users — 管理用户

• gohighlevel-pp-cli users get — 获取
• gohighlevel-pp-cli users search — 搜索某个位置的用户

workflows — 管理工作流

• gohighlevel-pp-cli workflows — 列出某个位置的工作流

查找合适的命令

知道自己想做什么，但不知道该用哪个命令时，直接询问 CLI：

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

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

使用示例

为周一的 L10 会议生成管道漏斗快照

gohighlevel-pp-cli opp funnel --pipeline "Non-KW" --tsv

按阶段汇总本地缓存中的商机；TSV 输出可直接粘贴到仪表板表格中。

找出在 Engaged 阶段停留 30 天以上的招募对象

gohighlevel-pp-cli opp stale --pipeline "Non-KW" --stage "Engaged" --days 30 --json

使用由同步差异构建的本地 stage_transitions 表——回答仅靠 GHL API 无法解答的问题。

为所有参加过培训的人批量添加标签

cat ~/Downloads/attendees.csv | gohighlevel-pp-cli contact bulk-tag --tag "Attended_2026-05-19" --dry-run

从标准输入读取电子邮件地址，每次处理 100 个，连接中断时会重试。去掉 --dry-run 即可应用更改。

根据自定义字段的名称查找其 ID

gohighlevel-pp-cli field id "Agent Affiliation"

根据易读的自定义字段名称返回不透明的 GHL 字段 ID。可搭配 gohighlevel-pp-cli sql "SELECT * FROM contacts WHERE ..." 使用，按自定义字段值查询，无需硬编码 ID。

跨实体查询（对缓存执行 SQL）

gohighlevel-pp-cli sql "SELECT c.email, o.name, o.monetaryValue FROM opportunities o JOIN contacts c ON o.contactId=c.id ORDER BY o.dateUpdated DESC LIMIT 50" --json

同步表之间的任意联接都可以通过一次查询完成——这正是 Agent 想要提出的查询形式。使用 --select 和带点号的路径提取嵌套字段，例如 customFields.value。

身份验证设置

GoHighLevel 使用 Private Integration Tokens（PIT）。请在环境中设置 GHL_PIT_TOKEN（前缀必须是小写 pit-；大写 Pit- 会返回 401 Invalid JWT）。也可以设置 GHL_LOCATION_ID 来指定活动子账户，或使用命名配置文件，通过 gohighlevel-pp-cli config use <name> 在 KWCP 和 THINK 等位置之间切换。

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

Agent 模式

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

• 可通过管道传递 — JSON 输出到 stdout，错误输出到 stderr

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

  gohighlevel-pp-cli calendars list --location-id 550e8400-e29b-41d4-a716-446655440000 --agent --select id,name,status
  

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

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

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

• 显式重试 — 仅当已存在的创建操作应视为成功时使用 --idempotent；仅当缺失的删除目标应视为成功时使用 --ignore-missing

响应封装

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

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

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时来源还是本地来源。只有当 stdout 是终端且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将人类可读的 N results (live) 摘要打印到 stderr——通过管道使用的客户端和 Agent，以及明确指定格式的运行，都会在 stdout 输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有问题时，请记录下来：

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

条目会本地保存在 ~/.gohighlevel-pp-cli/feedback.jsonl。除非设置了 GOHIGHLEVEL_FEEDBACK_ENDPOINT，并且传入 --send 或设置 GOHIGHLEVEL_FEEDBACK_AUTO_SEND=true，否则条目绝不会通过 POST 发送。默认行为仅保存到本地。

写下让你感到意外的地方，而不是提交错误报告。简短、具体、写成一行：这才是能不断积累价值的部分。

输出交付

每个命令都接受 --deliver <sink>。除了标准输出（stdout）之外，输出还会发送到指定的接收端（sink），也可以仅发送到该接收端，因此 Agent 无需手动通过管道传递，就能路由命令结果。支持三种接收端：

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

不支持的协议会被拒绝，并返回一条结构化错误，列出支持的协议。Webhook 请求失败时会返回非零退出码，并在标准错误（stderr）中记录 URL 和 HTTP 状态码。

命名配置文件

配置文件是保存的一组标志值，可在多次调用中重复使用。适用于定时运行的 Agent 每次都以相同配置调用同一命令的情况——HeyGen 的“Beacon”模式。

gohighlevel-pp-cli profile save briefing --json
gohighlevel-pp-cli --profile briefing calendars list --location-id 550e8400-e29b-41d4-a716-446655440000
gohighlevel-pp-cli profile list --json
gohighlevel-pp-cli profile show briefing
gohighlevel-pp-cli profile delete briefing --yes

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

退出码

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

参数解析

解析 $ARGUMENTS：

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

安装 MCP 服务

从此 CLI 发布的公共库条目或预构建版本安装 MCP 二进制文件，然后注册它：

claude mcp add gohighlevel-pp-mcp -- gohighlevel-pp-mcp

验证：claude mcp list

直接使用

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

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

4. 如果存在歧义，则进一步查看子命令帮助：gohighlevel-pp-cli <command> --help。