connect-hubspot-agent-cli

用途

本技能用于在 Claude Code 中安装并连接 HubSpot 的 Agent CLI，使智能体可以在终端对 HubSpot 门户执行批量与管理类操作。资料将 Agent CLI 定位为面向 AI 智能体的命令行工具：MCP 服务器偏向在对话中查找信息，而 CLI 偏向执行管理工作，例如批量读写、删除、管理属性和管道、创建 workflows，是 Claude Code 与门户之间较直接的连接方式。

主要能力

根据资料，CLI 可覆盖以下命令组：

objects：types、list、get、search、create、update、upsert、merge、delete
properties：list、get、create、update、delete、batch-read、batch-create、batch-archive
pipelines：list、get、create、update、delete，以及阶段相关变体
associations：list、create、delete、批量变体、labels、limits
workflows：list、get、create、update、delete
segments（别名 lists）：细分与列表管理
schemas：list、get、create、update、delete
owners：list
views、reports、imports、query、sequences、marketing、conversations、analytics、buyer-intent：资料提示用 hubspot help 查看
history：本机破坏性操作的本地日志

变更类命令从 stdin 读取 JSONL，一行一条记录；命令默认输出 JSONL，也支持 --format json 和 --format table。具体参数标志可能随 beta 变化，资料建议用 hubspot help <group> 查询准确标志。

使用方式

前置条件

Claude Code，且允许运行 shell 命令。
一个权限覆盖所需工作的 HubSpot 用户；资料称 CLI 在所有 HubSpot 套餐上可用。
若门户限制谁能连接应用，需 Super Admin 批准。
在 Claude Team 或 Enterprise 上，管理员可能需要将 api.hubapi.com 加入允许列表。

规划模式

用户模式：hubspot auth login，以用户自己的 HubSpot 权限执行，几乎总是首选；它不能超过本人在 UI 中能做的事。
管理员模式：将 HUBSPOT_ACCESS_TOKEN 设为服务密钥，以该密钥的权限范围执行；用于架构变更、关联批量操作等需要账户级访问的调用。

安装与登录

安装前先阅读脚本，再执行（资料原文）：

curl -fsSL https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.sh | sh

Windows PowerShell：

irm https://api.hubapi.com/hub/cli/backend/hub-cli/latest/install.ps1 | iex

二进制名为 hubspot，不同于 HubSpot 用于构建应用和 CMS 项目的开发者 CLI hs。

验证并登录：

hubspot --version

hubspot auth login

登录会打开浏览器，需审阅请求的权限并连接。

确认所在门户：

hubspot whoami

将账户名称和 ID 读回给用户，等待其确认是目标门户，尤其适用于可访问多个账户的人。

可选安装 HubSpot 官方为 CLI 提供的技能：

npx skills add hubspot/agent-cli-skills

仅在命令需要时启用管理员模式，为当次会话在环境变量中放置服务密钥，之后移除：

export HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx

unset HUBSPOT_ACCESS_TOKEN

资料提醒：该变量与本仓库脚本从 .env 读取的是同一个；若在 shell 中导出，CLI 会静默进入管理员模式，因此任何写入前都应先 hubspot whoami。

执行后验证

先运行读取并比对门户：

hubspot owners list --format table

负责人姓名应是用户认识的人；若不是，说明账户不对，应停止并重新登录。首次真实写入前，先用 --dry-run 运行该命令，与用户一起阅读预览，熟悉防护机制。

适用场景

资料给出的适用场景是一次性批量与管理任务，且需有人监督；查资料和抽查可交给 MCP。若存在针对该任务的脚本化技能，应优先使用技能，因为技能带有阈值、导出和回滚说明。当没有技能覆盖该任务时，再使用 CLI，并自行应用安全规则。

限制与注意事项

处于 beta：资料称 HubSpot 明确命令、标志和行为可能不经通知改变；应把它当作受监督会话中的强力工具，而不是任何计划任务的依赖。若本技能中的标志被拒绝，应以 hubspot help 为准。
速率与大小限制未公开：HubSpot 未发布 CLI 的限制，超大任务应拆成可逐个验证的文件，并预期适用一般 API 限制。
收入记录为只读，除非 Super Admin 让账户加入单独的收入 beta。
用户模式继承盲区：用户看不到的团队记录，CLI 也看不到，“完整”导出可能静默不完整。
回滚：hubspot auth logout 可退出；在 HubSpot 的 Settings > Integrations > Connected Apps 撤销连接。hubspot history 列出本机执行的破坏性操作。删除的 CRM 记录可在 90 天内从回收站恢复；更新覆盖的属性值除非事先导出否则不可恢复；删除的 workflows 无法通过任何 API 恢复。
hubspot 不是 hs：hs 是开发者 CLI，其 hs mcp setup 安装的是用于构建应用的开发者 MCP 服务器，不管理 CRM 数据。

安全使用规则（资料要求）

每次写入前先 --dry-run，向用户展示预览并等待确认；部分破坏性命令若无 dry run 产生的摘要会拒绝执行。
变更前先导出受影响记录到 data/audit-logs/（该目录已 gitignore，因导出可能含个人数据）：

hubspot objects search --type contacts --format jsonl > data/audit-logs/contacts-before.jsonl

自行设置阈值：变更前先计数，若数量超过用户预期，应停下询问。
在同一会话中确认门户：每次写入前运行 hubspot whoami，不凭记忆。
默认不要在管理员模式下删除：服务密钥会绕过按用户权限检查。
将生成的 JSONL 视为未受信任内容：批量文件是提案，应先展示样本和行数，再管道输入写入命令。