cargo-connection

Cargo CLI — 接続

コネクターと連携機能の管理：コネクターの一覧表示、利用可能な連携機能の検索、認証済みコネクターインスタンスの管理を行います。

JSON レスポンスの完全な構造については、references/response-shapes.md を参照してください。 よくあるエラーと解決方法については、references/troubleshooting.md を参照してください。 コネクターの CRUD と検索の例については、references/examples/connectors.md を参照してください。 利用可能な連携機能の一覧表示と OAuth フローについては、references/examples/integrations.md を参照してください。 サードパーティ製コネクターのレート制限への対処と、ワークフローでの再試行設定については、cargo-orchestration/references/polling.md と cargo-orchestration/references/troubleshooting.md を参照してください。ネイティブ連携機能にはレート制限はありません。

初期設定

すでにサインイン済みで（cargo-ai whoami がワークスペースを返す場合）、次のセクションに進んでください。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

すべてのコマンドは JSON を標準出力に出力します。失敗時はゼロ以外の終了コードと {"errorMessage": "..."} を返します。実行またはバッチを作成するコマンドはすべて非同期です。--wait-until-finished を渡すか、対応する get をポーリングしてください。スキルバンドル全体がインストールされている場合は、../cargo/references/prerequisites.md に CLI のバージョン固定、トークンスコープ、管理者専用の機能について記載されています。

主な概念

連携機能： 外部サービスの種類（例：HubSpot、Clearbit、Salesforce）です。連携機能によって、利用可能なアクションが定義されます。

コネクター： 連携機能の認証済みインスタンスです。1つの連携機能に複数のコネクターを紐付けられます（例：異なる2つの HubSpot アカウント）。ワークフローのノードグラフで参照するのがコネクターです。

まずリソースを検索する

アクションを探していますか？カタログを閲覧するのではなく、検索してください。 2つのキーワード検索で全機能を網羅できます。どちらも integration list のページ送りや、integration get のペイロード全体を読むより効率的です。

cargo-ai orchestration action list <query>                # START HERE — connector + native + tools + agents.
                                                          # Returns a ready-to-run action object (connectorUuid
                                                          # resolved) and the action's credit costs.
cargo-ai connection action search <query> --credits-only  # connector catalog only, but filters by
                                                          # "is it paid", which `action list` cannot.

必要なのがアクションではなく連携機能（認証フィールド、抽出器、またはすでに選択したアクションの入力スキーマ全体）である場合は、カタログコマンドを使ってください。

cargo-ai connection connector list                        # all authenticated connectors
cargo-ai connection integration list                      # all available integration types
cargo-ai connection integration list --search "hubspot"   # search by name
cargo-ai connection integration get <slug>                # one integration's actions + input schemas
cargo-ai connection native-integration get                # built-in Cargo actions only (NOT third-party)

非推奨の連携機能は、デフォルトではカタログに表示されません。 integration list、action list、action search は、--is-deprecated true を渡さない限り非推奨の項目を除外します。integration get <slug> は常に項目を1つ返し、isDeprecated: true と、末尾に (deprecated) が付いた表示名を含みます。これらには新たに接続できません。既存のコネクターは引き続き動作しますが、新しいワークフローで使用しないでください。CLI 1.0.92 では、自己参照型の cargo 連携機能を含む2つが非推奨になりました。一覧を覚えておくのではなく、フラグを確認してください。閲覧して見つけた連携機能を提案する際は、action list から見つけた場合を除き、必ず isDeprecated を確認してください。

どちらのアクション検索を使うべきか？

	orchestration action list	connection action search
対象	コネクター、ネイティブ機能、ツール、エージェント	コネクターカタログのみ
返される内容	実行可能な action オブジェクト。connectorUuid、ワークスペースのコネクター、credits を含み、自動補完されます	integrationSlug + actionSlug、カテゴリ、credits — アクションは自分で組み立てます
フィルター	--kind、--integration-slug、--category、--is-deprecated、--limit	--category、--integration、--credits-only、--is-deprecated、--limit
必要条件	CLI ≥ 1.0.66	CLI ≥ 1.0.36

デフォルトでは action list を使ってください。実行可能な項目を返すのは、このコマンドだけです。action search は、それだけが答えられる「該当する有料アクションはどれか？」（--credits-only）を調べる場合に使います。どちらのコマンドも、アクションのスラッグまたは名前との一致、連携機能との一致、説明文との一致の順に結果をランク付けし、クエリ内のすべての語句との一致を必要とします。

integration get と native-integration get

この2つのコマンドは異なるアクションのセットを返すため、互換性はありません。

コマンド	サードパーティサービスのアクション（HubSpot、Salesforce、Clearbit など）	Cargo 組み込みアクション（HTTP、変換、ユーティリティ）	使用する場面
integration get <slug>	✓	✗	特定のサードパーティサービスのアクションが必要な場合 — HubSpot、Salesforce、Clearbit などにはこちらを使用します。
native-integration get	✗	✓	特定のサードパーティコネクタに属さない Cargo ネイティブ機能が必要な場合

例： HubSpot 固有のアクションを探すには、integration get hubspot を使用します。native-integration get ではそれらは返されません。

クイックリファレンス

cargo-ai connection connector list --integration-slug <slug>
cargo-ai connection connector create --integration-slug <slug>   # hosted form in the browser
cargo-ai connection connector create --integration-slug <slug> --slug <slug> --name <name> --config '<json>'
cargo-ai connection connector update --uuid <uuid> --name <name>
cargo-ai connection connector remove <connector-uuid>
cargo-ai connection connector get <connector-uuid>
cargo-ai connection connector autocomplete --connector-uuid <uuid> --slug <slug> --params '<json>'
cargo-ai connection connector get-dynamic-schema --connector-uuid <uuid> --slug <slug> --params '<json>'
cargo-ai connection custom-integration list
cargo-ai connection integration list
cargo-ai connection integration get <slug>
cargo-ai connection integration get-documentation <slug>
cargo-ai connection native-integration get

コネクタ

コネクタは、外部サービスへの認証済み接続です。

# List all connectors
cargo-ai connection connector list

# Create a connector: no flags beyond --integration-slug opens the hosted form and waits
cargo-ai connection connector create --integration-slug clearbit

# Non-interactive: --config (shape depends on the integration) plus --slug and --name
cargo-ai connection connector create \
  --integration-slug clearbit \
  --slug clearbit_production \
  --name "Clearbit - Production" \
  --config '<integration-specific JSON>'

# Update a connector
cargo-ai connection connector update --uuid <connector-uuid> --name "Clearbit - Staging"

# Throttle and cache a connector (on create or update)
cargo-ai connection connector update --uuid <connector-uuid> \
  --rate-limit '{"unit":"minute","max":100,"strategy":"spread"}' \
  --cache-ttl-milliseconds 86400000

# Remove a connector
cargo-ai connection connector remove <connector-uuid>

# Check if a connector slug is taken
cargo-ai connection connector exists-by-slug --slug clearbit_production

注： --config を指定する場合は --slug（一意の識別子）と --name（表示名）が必須であり、指定しない場合は拒否されます（ホスト型フォームではこれらの入力を求められます）。OAuth ベースのインテグレーションでは、認証フローは connection integration complete-oauth で別途完了します。

レート制限とキャッシュはコネクタごとに設定されます。 --rate-limit は {"unit": "second" | "minute" | "hour" | "day", "max": <n>, "strategy": "spread" | "burst"} を指定します。spread は呼び出しを均等な間隔で行い、burst は呼び出しを通した後に待機します。また、"second" を指定した burst は拒否されます。1つの API キーを複数のプレイで共有する場合は、プロバイダー自身の上限より低い値に設定してください。--cache-ttl-milliseconds を設定すると、TTL 内にワークフローノードの計算後の設定が完全に一致する場合、プロバイダーを呼び出す代わりにキャッシュ済みの結果を返します。その場合、プロバイダーのクレジットは 0 です。これはアクションがキャッシュに対応しているインテグレーションでのみ有効で、それ以外では無視されます。エンリッチメント用コネクタに1日の TTL を設定すると、重複するバッチ間の重複排除を無料で行えます。

インテグレーション

インテグレーションは、利用可能なサービスとそのコネクタアクションを定義します。

# List all available integrations
cargo-ai connection integration list

# Filter by category
cargo-ai connection integration list --category enrichment

# Search by name
cargo-ai connection integration list --search "hubspot"

# Find by exact slug(s)
cargo-ai connection integration list --slugs clearbit

# Only integrations that have actions (usable in workflow nodes)
cargo-ai connection integration list --has-actions true

# Only integrations that have extractors (can sync data into models)
cargo-ai connection integration list --has-extractors true

# Get built-in Cargo actions and extractors (NOT third-party connector actions)
cargo-ai connection native-integration get

インテグレーションのカテゴリ： engagement、marketing、sales、finance、analytics、freeform、success、support、enrichment、storage、custom。

特定のサードパーティサービス（HubSpot、Salesforce など）で利用できるすべてのアクションを確認するには、integration get <slug> を使用します。native-integration get は Cargo 組み込みアクション専用です。HubSpot などのサービス固有のアクションは返されません。アクションはワークフローノードのグラフで actionSlug を使って参照します（cargo-orchestration スキルの references/nodes.md を参照）。

カスタムインテグレーション

カスタムインテグレーションとは、自分でホストするインテグレーションです。Cargo のインテグレーションプロトコル（GET /manifest、POST /actions/<slug>/execute、POST /extractors/<slug>/fetch（および /count）、POST /autocompletes/<slug>、POST /dynamicSchemas/<slug>）に対応する HTTP サーバーで、ワークスペースに登録すると、そのアクションとエクストラクターがカタログの項目と並んで表示されます。実行場所は、自分のサーバー（external）または Cargo Hosting ワーカー（worker）のいずれかです。後者は cargo-ai hosting worker init <dir> --template custom-integration で作成できます。

cargo-ai connection custom-integration create --kind external --base-url https://integrations.example.com
cargo-ai connection custom-integration create --kind worker --worker-uuid <worker-uuid>
cargo-ai connection custom-integration list
cargo-ai connection custom-integration get <uuid>
cargo-ai connection custom-integration update --uuid <uuid> --base-url https://new.example.com   # or --worker-uuid; kind cannot change
cargo-ai connection custom-integration remove <uuid>

登録時にインテグレーションには生成された slug が割り当てられます。他のインテグレーションと同様に、connector create --integration-slug <that slug> でこのインテグレーションに対するコネクタを作成します。external のベース URL はパブリックに到達可能である必要があります。プライベートアドレスとループバックアドレスは拒否される（unsafeOutboundUrl）ため、ローカルサーバーにはトンネルが必要です。このワークスペースにワーカーが存在しない場合、worker は workerNotFound エラーになります。

コネクタのオートコンプリート — アクションフィールドで利用可能な値を取得する

一部のアクションフィールドでは自由入力を受け付けず、許可されている値をコネクタから動的に取得する必要があります。アクションの設定を確認するとき（integration get <slug> または native-integration get を使用）、jsonSchema と並んで表示される uiSchema を確認してください。フィールドの uiSchema に "ui:widget": "IntegrationAutocompleteWidget" が含まれている場合、そのフィールドの有効な値は connector autocomplete を使って必ず取得する必要があります。

オートコンプリートフィールドの検出方法

アクションの設定が次のようになっている場合：

{
  "jsonSchema": {
    "type": "object",
    "properties": {
      "objectType": { "type": "string", "description": "The object type" }
    }
  },
  "uiSchema": {
    "objectType": {
      "ui:widget": "IntegrationAutocompleteWidget",
      "ui:options": {
        "slug": "listObjects",
        "allowRefresh": true
      }
    }
  }
}

objectType フィールドにはオートコンプリートが必要です。ui:options.slug（"listObjects"）が、connector autocomplete に渡すオートコンプリートのスラッグです。

connector autocomplete の呼び出し方法

cargo-ai connection connector autocomplete \
  --connector-uuid <connector-uuid> \
  --slug <autocomplete-slug> \
  --params '{}'

フラグ	必須	説明
--connector-uuid	はい	オートコンプリートの対象となるコネクターの UUID
--slug	はい	uiSchema[field]["ui:options"].slug のオートコンプリートのスラッグ
--params	はい	パラメーターの JSON オブジェクト（不要な場合は {} を使用）
--value	いいえ	結果を絞り込む検索文字列
--refresh	いいえ	キャッシュを回避して最新の結果を取得

パラメーターを使ったオートコンプリート

一部のオートコンプリートフィールドは、別のフィールドの値に依存します。これは ui:options の params オブジェクトで示されます。

{
  "uiSchema": {
    "objectType": {
      "ui:widget": "IntegrationAutocompleteWidget",
      "ui:options": { "slug": "listObjects" }
    },
    "propertyName": {
      "ui:widget": "IntegrationAutocompleteWidget",
      "ui:options": {
        "slug": "listObjectProperties",
        "params": { "objectType": "$this.$parent.objectType" }
      }
    }
  }
}

ここでは、propertyName は選択した objectType に依存します。$this.$parent... 式を、選択した実際の値に置き換えます。

# 1. First, get the list of object types
cargo-ai connection connector autocomplete \
  --connector-uuid <uuid> --slug listObjects --params '{}'

# 2. Then, get properties for the chosen object type
cargo-ai connection connector autocomplete \
  --connector-uuid <uuid> --slug listObjectProperties \
  --params '{"objectType": "contacts"}'

レスポンス形式

{
  "results": [
    { "label": "Contacts", "value": "contacts" },
    { "label": "Companies", "value": "companies" },
    { "label": "Deals", "value": "deals" }
  ]
}

ノード設定では value フィールドを使用します。label は人間が読める表示名です。結果には、任意で description フィールドや parent フィールドが含まれる場合もあります。

動的スキーマ — 別の値に応じて形状が変わるフィールド

uiSchema に "ui:widget": "DynamicSchemaWidget" が含まれるフィールドには、固定スキーマがありません。サブフィールドは設定時にコネクターから取得します（たとえば、HubSpot のフォーム同意オプションは、選択した formId によって変わります）。オートコンプリートの場合と同様に、ui:options.slug とその params を使ってスキーマを取得し、$this.$parent… の参照を選択した値に置き換えます。

cargo-ai connection connector get-dynamic-schema \
  --connector-uuid <uuid> --slug getConsentOptions --params '{"formId":"<form-id>"}'

--slug には、アクションのスラッグではなく、ui:options の 動的スキーマのスラッグを指定します（CLI 1.0.128 より前のヘルプでは「action slug」と記載されていました）。レスポンスには schema（フィールドの JSON Schema）と uiSchema が含まれます。フィールドはそれに合わせて入力してください。検証に失敗するパラメーターの場合、エラーではなく 空の結果（schema なし）が返されるため、結果が空の場合は通常、パラメーターが不足しているか、名前が間違っています。

最初から最後までの例：HubSpot アクションの設定

# 1. Find your HubSpot connector UUID
cargo-ai connection connector list --integration-slug hubspot

# 2. Get HubSpot actions and inspect their config + uiSchema
cargo-ai connection integration get hubspot
# → The "findRecords" action has objectType with autocomplete slug "listObjects"

# 3. Fetch available object types
cargo-ai connection connector autocomplete \
  --connector-uuid <hubspot-connector-uuid> \
  --slug listObjects --params '{}'
# → Returns: contacts, companies, deals, tickets, etc.

# 4. Fetch properties for the chosen object type
cargo-ai connection connector autocomplete \
  --connector-uuid <hubspot-connector-uuid> \
  --slug listObjectProperties \
  --params '{"objectType": "contacts"}'
# → Returns: email, firstname, lastname, phone, etc.

# 5. Use these values in your workflow node config

ワークフローでのコネクターアクションの使用

コネクターアクションはワークフローグラフ内のノードとして使用します。アクションを使用するには：

# 1. Find your connector UUID
cargo-ai connection connector list
# → Filter the output by integrationSlug to find the right connector

# 2. Discover the action — search first, and only then read its schema
cargo-ai orchestration action list <keywords> --integration-slug <integration-slug>
cargo-ai connection integration get <integration-slug>
# → actions are keyed by actionSlug, with config.schema (input) for each
# → many actions also carry output.schema — the JSON Schema of what the action
#   emits; use it to wire downstream nodes instead of guessing (absent on some actions)
# → Or use get-documentation for a plain text overview
# → Or use native-integration get for built-in Cargo actions (not third-party)

# 3. Reference the connector and action in a node graph
# See cargo-orchestration references/nodes.md for the full node syntax

アクションの入力スキーマを読む — 入力値の渡し先

アクションの入力フィールドは、integration get <slug> の出力にある actions.<slug>.config.schema にあります（config.jsonSchema は、フォーム UI 向けに装飾された同じスキーマです）。アクションを呼び出す前に確認してください。フィールド名を推測してはいけません。

# the required input fields for an action:
cargo-ai connection integration get linkedin \
  | jq '.integration.actions.connectProfile.config.schema'
# → required: linkedinProfileUrl, identityIds

注意すべき点が2つあります。

• トップレベルのアクション（action execute / execute-batch）では、入力値はアクションの config ではなく、--data に渡します。 config.schema で定義されたフィールドは --data のペイロードです。アクション定義に config キーはありません。入力値を誤った場所に置いても、以前のように明確なエラーにはなりません。 古いバックエンドでは、呼び出しは A top-level action does not use action.config; pass the action's inputs via data instead. というエラーで拒否されていましたが、新しいバックエンドでは、送信時に config が削除されるため、入力値が届きません。その結果、最初に必須フィールドが欠けている場合は実行前に拒否され（invalidData）、必須フィールドがない場合は何もせずに実行されます。いずれの場合も、config に関するメッセージは表示されません。アクションが理由もなく空の結果を返したり拒否されたりする場合は、入力値が --data に指定されているか確認してください。--data 内のキーのスペルが間違っている場合は、実行前に拒否されます（Unknown field: <key>）。（ワークフローのノードグラフ内では、同じフィールドをノードの config に指定します。詳しくは cargo-orchestration/references/nodes.md を参照してください。「--data であり、config ではない」というルールは、action execute / execute-batch に限られます。）
• 一部の入力は、オートコンプリートで事前に解決する必要があります。 フィールドの uiSchema に IntegrationAutocompleteWidget が含まれている場合は、connector autocomplete で値を取得してください（前述）。特に、LinkedIn のエンゲージメント／抽出アクション（connectProfile、visitProfile、extractEventAttendees、extractProfileViewers）では、実行する接続済みアカウントを示す identityIds が必要です。これは listIdentityIds オートコンプリートで解決してください。must match format "uuid" エラーは、その identity が指定されていないことを示します。

コネクタノードの例（Clearbit による企業情報の補完）：

{
  "uuid": "node-uuid",
  "slug": "enrich",
  "kind": "connector",
  "integrationSlug": "clearbit",
  "actionSlug": "enrichCompany",
  "connectorUuid": "<clearbit-connector-uuid>",
  "config": {
    "domain": {
      "kind": "templateExpression",
      "expression": "{{nodes.start.domain}}",
      "instructTo": "none",
      "fromRecipe": false
    }
  },
  "childrenUuids": ["end-node-uuid"],
  "fallbackOnFailure": false,
  "position": { "x": 0, "y": 166 }
}

ヘルプ

すべてのコマンドで --help を利用できます。

cargo-ai connection connector list --help
cargo-ai connection connector create --help
cargo-ai connection integration list --help