workflow-automation

どの CLI を使うか

2 つの異なる HubSpot CLI が紛らわしいほど似ているため、混同しないでください：

• hubspot — このスキルライブラリが対象とする HubSpot のエージェント CLI です。CRM データと自動化を管理し、ネイティブのワークフローコマンドを持っています：hubspot workflows list|get|create|update|delete。
• hs — HubSpot の開発者 CLI（@hubspot/cli）で、開発プロジェクトを構築するためのものです：テーマ、モジュール、サーバーレス関数、UI 拡張機能、プライベートアプリ（hs project、hs upload、hs create）。ワークフローレコードの作成や管理は行いません。

ワークフローを作成または管理するには、hs ではなく hubspot workflows ... を使用してください。

ここに記載されている内容が何かと食い違う場合は、hubspot workflows --help と hs --help が正式な情報源です。

リソース

ファイル	使用するタイミング
resources/workflow-json-reference.md	create/update のボディ形状 — アクショングラフ、分岐と収束、登録条件、フル PUT の落とし穴
resources/example-contact-flow.json	hubspot workflows create --file 向けの最小限の有効な CONTACT_FLOW スケルトン
resources/example-branching-flow.json	分岐の収束を例示 — 2 つのパスが connection.nextActionId を 1 つの共有された下流アクションに向けている

正式な情報源

hubspot workflows --help には 5 つのサブコマンドが一覧表示されます：list、get、create、update、delete。search は存在しません — 名前で検索するには list | jq を使用します。JSONL のパイピング、ページネーション、および破壊的な dry-run/digest/confirm パターンについては、このスキルは bulk-operations/SKILL.md を基盤としています — まずそちらを再読してください。

認証 — OAuth ログインまたはサービスキー

すべての 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 を返す場合は、新しく追加された automation スコープが付与されるように hubspot auth login を再実行してください。

1. 一覧表示 + 名前で検索

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 の結果は 1 回の呼び出しで 100 件ごとにページネーションされるので、meta.next が空になるまで --after でループしてください — bulk-operations/SKILL.md の「ページネーション」を参照してください。その他の jq フィルターについては、bulk-operations の resources/json-patterns.md を参照してください。

2. 取得 + 形状の読み取り

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 など）を返します — これは create/update で必要な形状です。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 を参照してください。最も簡単な方法: JSON を手書きするのではなく、既存の類似ワークフローを get して開始テンプレートとして使うことです。

落とし穴: create --dry-run はボディを検証しません。 標準のドライランプレビュー（mutation_kind、target、impact）を出力し、API 呼び出しは行いません — ドライランが成功しても、入力が整形された JSON であることしか証明せず、有効な create であることは証明しません（type/flowType/objectTypeId/actions が欠けたボディでも ok:true が返り、プレビューにボディはエコーされません）。唯一の本当の検証は実際の create です。対照的に、update --dry-run は revisionId のような必須フィールドが欠けたボディを拒否します。

分岐と収束。 LIST_BRANCH アクションはフィルター条件でパスを分岐させます。各ブランチ — および defaultBranch — は、次に続くアクションへの connection を持ちます。接続は nextActionId でアクションを指定するため、ブランチは収束できます: 2 つのブランチを同じ actionId に向ければ、両方のパスが 1 つの共有アクションへ続き、重複はありません。resources/workflow-json-reference.md の分岐セクションと resources/example-branching-flow.json を参照してください。

4. 更新 — 完全な PUT、get-modify-put のラウンドトリップ

更新は完全な置き換えです。ボディには revisionId（get から取得）と type を含める必要があります。読み取り専用フィールド（createdAt、updatedAt、dataSources）は自動的に除去されます。更新はゲート制御されています: まずドライラン、次に --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"

ドライラン出力には apply_command_hint が含まれます — 引用符の問題を避けるため、そこから正確な確認文字列をコピーしてください。削除後、ワークフローは automation 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 を通じて設定してください — リスト ID は hubspot segments list / get で取得し、enrollmentCriteria の形式は実際の workflows get からコピーしてください（resources/workflow-json-reference.md を参照）。UI の手順は不要です。
• Sales Hub のシーケンスはワークフローとは別のサーフェスです: hubspot sequences はそれらを読み取ります（list --user-id <id>、get <id> --user-id <id>、enrollments <contact_id>）が、読み取り専用です — create/update/delete/enroll はなく、CRM オブジェクトタイプでもありません（Sales Hub Professional 以上、automation.sequences.read スコープ）。ワークフローの create/update/delete は hubspot workflows に属します。このサーフェスは拡大しています。API が存在しないと判断する前に hubspot --help / CHANGELOG.md を再確認してください。
• dataSources は読み取り専用です — 更新を通じて再設定することはできません。