workflow-automation

Which CLI

HubSpot 有两个名称相似、容易混淆的 CLI——请勿混用：

• hubspot — 此技能库面向的 HubSpot Agent CLI。它用于管理 CRM 数据和自动化，支持原生工作流命令：hubspot workflows list|get|create|update|delete。
• hs — HubSpot 开发者 CLI（@hubspot/cli），用于构建开发项目：主题、模块、无服务器函数、UI 扩展和私有应用（hs project、hs upload、hs create）。它不能创建或管理工作流记录。

要创建或管理工作流，请使用 hubspot workflows ...，而非 hs。

如果这里的内容与实际情况有出入，请以 hubspot workflows --help 和 hs --help 为准。

Resources

File	When to use
resources/workflow-json-reference.md	创建/更新时的请求体结构——操作图、分支/汇合、注册条件、全量 PUT 的陷阱
resources/example-contact-flow.json	供 hubspot workflows create --file 使用的最简有效 CONTACT_FLOW 框架
resources/example-branching-flow.json	展示分支汇合——两个路径将 connection.nextActionId 指向同一个下游操作

Source of truth

hubspot workflows --help 列出了五个子命令：list、get、create、update、delete。没有 search——按名称查找可使用 list | jq。对于 JSONL 管道传输、分页，以及具有破坏性的 dry-run/digest/confirm 模式，本技能基于 bulk-operations/SKILL.md 构建——请先重新阅读该文件。

Auth — OAuth login or service key

每个 hubspot workflows 命令都支持 hubspot auth login（用户 OAuth）和 HUBSPOT_ACCESS_TOKEN（服务密钥）。 v4 flows API 接受用户令牌；它所需的 automation 范围现已包含在 CLI 应用可请求的范围中，因此只需运行 hubspot auth login：

hubspot auth login          # user OAuth — grant the "automation" scope when prompted
# or
export HUBSPOT_ACCESS_TOKEN=<service-key>   # create at Settings → Integrations → Service keys
hubspot workflows list

如果用户令牌因缺少范围而返回 403，请重新运行 hubspot auth login，以授予新增的 automation 范围。

1. List + find by name

hubspot workflows list                       # JSONL: id, name, isEnabled, type, objectTypeId, revisionId
hubspot workflows list --format table        # for human scanning

# Find by name — case-insensitive substring
hubspot workflows list | jq -c 'select(.name | test("Welcome"; "i"))'

# Exact match
hubspot workflows list | jq -c 'select(.name == "MQL Nurture")'

List 仅读取 /automation/v4/flows。不会返回 /automation/v3/workflows 中基于经典联系人的工作流，因此结果为空不一定表示缺少自动化范围。v4 结果每次调用最多分页返回 100 条；请使用 --after 循环请求，直到 meta.next 为空——参见 bulk-operations/SKILL.md 中的“Pagination”。更多 jq 过滤器请参见 bulk-operations 中的 resources/json-patterns.md。

2. Get + read shape

hubspot workflows get 12345678                            # one
hubspot workflows get 12345678 87654321                   # batch positional
printf '%s\n' 12345678 87654321 | hubspot workflows get   # batch stdin
hubspot workflows get 12345678 > workflow.json            # save for editing

Get 会返回完整请求体（actions、enrollmentCriteria、revisionId 等），这是创建/更新所需的结构。请参见 resources/workflow-json-reference.md。

3. 从 JSON 创建

hubspot workflows create --file workflow.json --dry-run
hubspot workflows create --file workflow.json
cat workflow.json | hubspot workflows create         # stdin also works

设置 type（CONTACT_FLOW 或 PLATFORM_FLOW）、flowType（WORKFLOW）和 objectTypeId（例如，联系人对应 0-1）——创建时这些字段均为必填项。正文结构请参阅 resources/workflow-json-reference.md，最简模板请参阅 resources/example-contact-flow.json。最简单的做法：get 一个类似的现有工作流，将其作为起始模板，而不是手动编写 JSON。

注意事项：create --dry-run 不会验证正文。 它会打印标准的 dry-run 预览（mutation_kind、target、impact），且不会调用 API——dry-run 显示成功只能证明输入是格式正确的 JSON，不能证明它是有效的创建请求（缺少 type/flowType/objectTypeId/actions 的正文仍会返回 ok:true，且预览不会回显正文）。只有实际执行 create 才会进行真正的验证。相比之下，update --dry-run 会拒绝缺少 revisionId 等必填字段的正文。

分支与汇合。 LIST_BRANCH 操作会根据筛选条件分叉路径；每个分支以及 defaultBranch 都包含一个指向后续操作的 connection。由于连接通过 nextActionId 指向操作，分支可以汇合：将两个分支都指向同一个 actionId，两条路径就会继续执行同一个共享操作，无需重复创建。请参阅 resources/workflow-json-reference.md 中的分支部分和 resources/example-branching-flow.json。

4. 更新——完整 PUT，get-modify-put 往返流程

更新会完整替换。正文必须包含 revisionId（来自 get）和 type。只读字段（createdAt、updatedAt、dataSources）会自动剥除。更新需要经过安全门控：先执行 dry-run，然后使用 --digest <hash> --confirm <flowId> 重新运行。

# 1. Fetch current state
hubspot workflows get 12345678 > workflow.json

# 2. Edit workflow.json (preserve revisionId, type, and any field you want to keep)

# 3. Dry-run — emits a digest
hubspot workflows update 12345678 --file workflow.json --dry-run

# 4. Apply — confirm value is the flow id
hubspot workflows update 12345678 --file workflow.json \
  --digest blast-xxxxxxxx --confirm 12345678

**注意事项：**不完整的正文会静默清除字段。只发送 actions 会清空 enrollmentCriteria。请始终从完整的 get 响应开始。

5. 删除——具有破坏性，请参阅批量操作安全流程

# 1. Dry-run — emits a digest + the confirm hint
hubspot workflows delete 12345678 --dry-run

# 2. Re-run with digest + confirm. Confirm value is the workflow's NAME, not its id.
hubspot workflows delete 12345678 --digest blast-xxxxxxxx --confirm "New lead routing"

dry-run 输出中包含 apply_command_hint——请复制其中完整的确认字符串，以免遇到引号问题。删除后无法通过自动化 API 恢复工作流；请运行 hubspot history --since 1h 查找审计记录。完整的安全模式（摘要、5 分钟有效期、历史记录恢复）已记录在 bulk-operations/SKILL.md 的 “Safe destructive workflow” 中。

已知限制

• list 仅涵盖 v4 工作流。不会返回来自 /automation/v3/workflows 的经典联系人工作流。
• 没有 hubspot workflows search——可用 list | jq 作为替代方案。
• hubspot segments 提供 CRM 列表（list、get、create、update、update-filters、delete、restore、members-list / members-add / members-remove）。列表成员资格注册触发器属于工作流正文（enrollmentCriteria）的一部分，因此请通过 hubspot workflows create / update 进行配置——使用 hubspot segments list / get 获取列表 ID，并从真实的 workflows get 结果中复制 enrollmentCriteria 结构（参见 resources/workflow-json-reference.md）。无需执行 UI 步骤。
• Sales Hub 序列与工作流是不同的功能：hubspot sequences 可读取序列（list --user-id <id>、get <id> --user-id <id>、enrollments <contact_id>），但仅支持读取——不支持创建/更新/删除/注册，也不是 CRM 对象类型（需要 Sales Hub Professional+ 和 automation.sequences.read 范围）。工作流的创建/更新/删除仍由 hubspot workflows 负责。该功能范围仍在扩展；在假定某个 API 不存在之前，请重新检查 hubspot --help / CHANGELOG.md。
• dataSources 为只读字段——无法通过更新重新配置。