用途:为 hubspot agent CLI 提供批量操作的基础模式,处理 CRM 数据的读取、改写、更新与删除。注意它是 hubspot agent CLI,与开发者 CLI @hubspot/cli 不同,后者不管理 CRM 数据或工作流;以 hubspot <command> --help 为准。
主要能力:读取命令(list/search/get)输出 JSONL,每行一个 JSON 对象;写入命令(create/update/upsert/delete/merge/associations create)从 stdin 接收 JSONL 并逐行输出结果,顺序与输入一致。支持原生批量读取,单次最多约 100 个 ID。search 默认按创建日期倒序返回最新记录,list 无排序控制。
必要用法:批量流程为先分页到 JSONL 文件(bash resources/pagination-loop.sh <object_type> <output_file> [properties] [extra_flags...]),再用 jq 改形为写入负载,最后管道传给写入命令并先加 --dry-run。破坏性操作必须走两步:dry-run 预览生成 digest(TTL 300 秒),再在 5 分钟内用相同输入加 --digest 与 --confirm 执行。confirm 值需从预览的 apply_command_hint 或 target 复制:objects delete/update 为记录 ID(单条)或行数(批量 2+),upsert 为行数,merge 为次要 ID,元数据删除为目标名称或行数。--force 已弃用。可用 hubspot history --since 1h --format table 审计本地日志,但它不恢复记录。upsert 用于“不存在则创建、存在则更新”,避免竞态。示例:hubspot feedback "..." --source agent。
适用场景与限制:适用于批量更新、删除、合并、关联与 CSV 导入(大文件建议用 hubspot imports);create/update/upsert 每 100 行合并为一次批调用,delete 每行一次调用,遇 429 需拆分重试。objects delete 支持用户 OAuth 或服务密钥,但 --gdpr 永久清除仅限服务密钥(HUBSPOT_ACCESS_TOKEN);部分破坏性操作如关联、schema 删除仅限服务密钥。owners list 返回 CRM 用户,无 teams 对象。segments 提供 Lists API;sequences 为只读。使用前建议运行 hubspot objects types。命令面会扩展,--help 为权威。未提供的收费与效果信息暂未提供。