用 hubspot CLI 做批量 CRM…

当需要通过 hubspot CLI 对 CRM 记录做批量读取、更新、删除、upsert 或关联时，用 JSONL 管道 + 分页 + dry-run/digest 确认的安全流程。

适用场景

解决思路

1. 先确认工具：这是 `hubspot` agent CLI；`hs` 开发者 CLI（`@hubspot/cli`）是另一个工具，不管理 CRM 数据或工作流。以 `hubspot <command> --help` 为准，若本文档与 `--help` 冲突，信任 `--help` 并告知用户。会话开始时运行一次 `hubspot objects types` 查看该 portal 中存在的对象类型（标准 + 自定义）。
2. 用 `hubspot feedback "<消息>" --source agent` 向 CLI 维护者反馈问题（bug、使用困惑、用户不满、无法完成的需求、希望存在的工具/能力），一行即可，会关联当前 HubSpot 账号且不阻塞任务，发完继续干活。
3. 理解输出格式：所有读命令（`list`、`search`、`get`）输出 JSONL，每行一个 JSON 对象，形如 `{"id":"123","properties":{...},"createdAt":"...","updatedAt":"...","archived":false,"url":"..."}`。用 `--properties email,firstname` 限制服务端返回字段；下游 `jq` 用 `.properties.email`，不要用 `.prop_email`。
4. 理解写命令的输入输出：写命令（`create`、`update`、`upsert`、`delete`、`merge`、`associations create`）从 stdin 接收 JSONL 并输出 JSONL，每行输入对应一行结果 `{"id":"123","ok":true,"data":{...}}` 或 `{"id":"123","ok":false,"error":{"status":...,"message":"..."}}`，结果顺序与输入顺序一致。
5. 批量读取时不要逐条调用：CLI 原生支持多个 ID，绝不要用 `xargs -I{} hubspot objects get ...` 为每条记录启动一个进程。可用位置参数（小规模已知列表）`hubspot objects get --type contacts 12345 67890 23456 --properties email,firstname`；或从其他命令管道输入 `hubspot associations list --from companies:67890 --to contacts | jq -c '{id}' | hubspot objects get --type contacts --properties email,firstname,jobtitle`；或直接传裸 ID `printf '12345\n67890\n23456\n' | hubspot objects get --type contacts --properties email`。单次 `hubspot objects get` 通过批量端点最多读约 100 个 ID，更多则按 100 分块。
6. 批量操作固定流程：先分页、再重塑、最后写入。对某类型全部记录（或某过滤条件的全部匹配）操作时，始终先用 `pagination-loop.sh`，绝不要用裸 `list` 或 `search` 去“看看有多少条”——裸调用最多返回 100 条，之后还得重新拉取。标准模式：1) 分页所有记录到 JSONL 文件；2) 用 `jq` 重塑为写入载荷；3) 先加 `--dry-run` 管道到写命令（`update`、`delete` 等）。
7. 分页：`list` 和 `search` 每次最多返回 100 条。用 `bash resources/pagination-loop.sh <object_type> <output_file> [properties] [extra_flags...]` 收集所有页到单个 JSONL 文件，例如 `bash resources/pagination-loop.sh contacts /tmp/contacts.jsonl email,firstname,lastname`、`bash resources/pagination-loop.sh contacts /tmp/leads.jsonl email,firstname '--filter' 'lifecyclestage=lead'`、`bash resources/pagination-loop.sh deals /tmp/deals.jsonl`。脚本自动按 `--after` 游标翻页，进度打印到 stderr，JSONL 写入输出文件。作为单个前台命令运行，不要后台运行或内联重建循环。
8. 批量写入时始终用管道，并按目标命令构造每行形状：`objects create` 用 `{"properties":{"field":"value"}}`；`objects update` 用 `{"id":"123","properties":{"field":"value"}}`；`objects upsert` 用 `{"idProperty":"email","id":"jane@example.com","properties":{...}}`（或一次性用 `--id-property email`）；`objects delete` 用 `{"id":"123"}`；`objects merge` 用 `{"primary":"123","secondary":"456"}`；`associations create` 用 `{"from":"contacts:123","to":"companies:456"}`。`from`/`to` 中用复数对象名（`contacts:` 而非 `contact:`）。
9. 安全破坏性流程：每个破坏性操作（`delete`、`merge`、批量 `update`）都支持 `--dry-run`，门控取决于行数。≤100 行时 dry-run 每条记录输出一行预览 `{"ok":true,"dry_run":true,"executed":false,"mutation_kind":"RecordMutation","command":"objects delete contacts","target":{"kind":"contacts_record","id":"123","name":"123"}}`，去掉 `--dry-run` 重跑即可执行。>100 行时 dry-run 输出单行 `BulkData`，含 digest 和 `apply_command_hint`，形如 `{"ok":true,"dry_run":true,"executed":false,"mutation_kind":"BulkData","portal":"123456","target":{"name":"202 records"},"impact":{"records_affected":202,"reversible":false},"digest":"blast-29cfdd48b583","expires_in_seconds":300,"apply_command_hint":"hubspot objects delete contacts --digest blast-29cfdd48b583 --confirm '202'"}`；必须在 5 分钟内用 `--digest <hash> --confirm <value>` 重跑，`confirm` 值是记录数（删除）或 secondary ID（合并），从 `apply_command_hint` 读取。三步模式：1) 预览 `hubspot objects search --type contacts --filter "lifecyclestage=subscriber" | jq -c '{id}' | hubspot objects delete --type contacts --dry-run | tee /tmp/preview.jsonl`；2) 提取 digest 和 confirm 值（仅 >100 行时存在）`digest=$(jq -r 'select(.mutation_kind=="BulkData") | .digest' /tmp/preview.jsonl)`、`confirm=$(jq -r 'select(.mutation_kind=="BulkData") | .impact.records_affected' /tmp/preview.jsonl)`；3) 用相同输入重新管道执行 `hubspot objects search --type contacts --filter "lifecyclestage=subscriber" | jq -c '{id}' | hubspot objects delete --type contacts --digest "$digest" --confirm "$confirm"`。
10. 用 `hubspot history` 恢复/审计：每个破坏性操作（及其 dry-run）都记录在本地。查看最近一小时发生了什么以及哪些可逆：`hubspot history --since 1h --format table`、`hubspot history --since 24h --kind BulkData`（仅批量操作）、`hubspot history --since 7d --kind MetadataDestroy`（schema 删除）。`history` 目前不能恢复记录，只是审计日志；若误删，捕获 history 行并告知用户通过 UI 恢复。
11. 用 upsert 代替 search-then-create：对“不存在则创建、存在则更新”（enrichment 模式）用 `upsert`，每条记录一次 CLI 调用，无竞态。例如 `cat external.jsonl | jq -c '{idProperty:"email", id:.email, properties:{firstname:.first, lastname:.last, company:.company}}' | hubspot objects upsert --type contacts --dry-run`；或一次性设置 idProperty：`cat external.jsonl | jq -c '{id:.email, properties:{firstname:.first}}' | hubspot objects upsert --type contacts --id-property email`。
12. 限流卫生：`update`/`delete`/`upsert` 背后没有真正的批量端点，CLI 对每行 stdin 发一次 API 调用。管道 5 万行文件前先用 `head -n 50` 测试。若 API 开始返回 429，逐行输出会显示 `{"ok":false,"error":{"status":429,...}}`，拆分输入文件并重试失败行。
13. 常用重塑（完整集合见 `resources/json-patterns.md`，90% 场景只需这两个）：读 → 更新载荷 `hubspot objects search --type contacts --filter "industry=Tech" | jq -c '{id, properties:{lifecyclestage:"marketingqualifiedlead"}}' | hubspot objects update --type contacts`；搜索 → 删除列表 `hubspot objects search --type contacts --filter "!email" | jq -c '{id}' | hubspot objects delete --type contacts --dry-run`。
14. 已知约束：某些破坏性操作在用户 OAuth（浏览器登录）下可能被阻止，若 CLI 返回权限错误，运行删除时设置 `HUBSPOT_ACCESS_TOKEN`（私有应用 token）。`hubspot owners list` 返回 CRM 用户，没有 `teams` 对象；团队级操作需在客户端按 `hubspot_owner_id` 分组。当前 CLI 表面没有 Lists API，也没有 sequences/cadences API。

适用边界 · 注意事项

• 不要用 `hs` 开发者 CLI（`@hubspot/cli`）来管理 CRM 数据或工作流，它是另一个工具。
• 不要用 `xargs -I{} hubspot objects get ...` 逐条读取，会为每条记录启动一个 CLI 进程。
• 不要用裸 `list` 或 `search` 去“检查有多少条记录”，最多只返回 100 条，之后仍需重新拉取。