用途：把外部 CSV/JSONL 记录按自然键（联系人 email、公司 domain）一次写入 HubSpot CRM，创建或更新同一调用完成，避免 search→create 的竞态。
主要能力：hubspot objects upsert --type X --id-property <natural-key> 从标准输入读取 JSONL，每行形如 {"id":"jane@example.com","properties":{...}}，逐行输出 {"id":"123","ok":true,"data":{...}} 或 {"ok":false,"error":{...}}，顺序与输入一致；CLI 每请求批量 100 行，不自行添加字段。
使用方式：先阅读 bulk-operations/SKILL.md（JSONL 管道、dry-run/digest、history、限流规范）。CSV 转 JSONL 示例：csvjson external.csv | jq -c '.[]' > external.jsonl。预览用 --dry-run 并用 tee 保存，再提取 digest 与 confirm（upsert 的 confirm 恒为行数），以同一管道重跑执行。自然键需统一小写，CRM 为精确匹配；属性名用 hubspot properties list --type contacts 确认，不要硬编码。公司场景替换为 --type companies --id-property domain，并把 .domain|ascii_downcase 作为 id。结果可用 jq 按 .ok 拆分为成功/失败文件，检查 .error.status，修好输入后仅重跑失败项。CLI 不标记创建还是更新，可用 .data.new 或对比 .data.createdAt 与 .data.updatedAt 区分。遇 429 拆分更小批次重跑；400 通常是属性名错误或枚举值非法。upsert 本身非破坏性，但回写可能覆盖已有字段，务必先 --dry-run 抽查；恢复可用 hubspot history --since 1h。
仅读取匹配时可改用重复 --filter（每个 flag 一组 OR），但每次调用最多 5 组，6 组以上返回 400，需分批。
适用场景：联系人/公司数据的批量富化回写，或先查后改。限制：单请求 100 行、OR 过滤 5 组上限、自然键须为 CRM 属性；官方未提供更多费用或平台信息。