Back to Details

cargo-connection

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cargo CLI — Connections

Cargo CLI — 连接器管理

Connector and integration management: listing connectors, discovering available integrations, and managing authenticated connector instances.
See 
references/response-shapes.md
for full JSON response structures. See 
references/troubleshooting.md
for common errors and how to fix them. See 
references/examples/connectors.md
for connector CRUD and discovery examples. See 
references/examples/integrations.md
for listing available integrations and OAuth flows. For third-party connector rate limit handling and retry config in workflows, see 
cargo-orchestration/references/polling.md
and 
cargo-orchestration/references/troubleshooting.md
. Native integrations do not have rate limits.
连接器与集成管理：列出连接器、发现可用集成，以及管理已认证的连接器实例。
如需完整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
。原生集成无速率限制。

Prerequisites

前置条件

bash
npm install -g @cargo-ai/cli
cargo-ai login --oauth                                  # browser sign-in (recommended)
bash
npm install -g @cargo-ai/cli
cargo-ai login --oauth                                  # 浏览器登录（推荐）

or: cargo-ai login --token <your-api-token> # workspace-scoped API token (non-interactive)

或：cargo-ai login --token <your-api-token> # 使用工作区范围的API令牌登录（非交互式）

Pin a default workspace at login (with --oauth)

登录时固定默认工作区（搭配--oauth使用）

cargo-ai login --oauth --workspace-uuid <uuid>

Verify with `cargo-ai whoami`. All commands output JSON to stdout. Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.

Failed commands exit non-zero and return `{"errorMessage": "..."}`.
cargo-ai login --oauth --workspace-uuid <uuid>

使用`cargo-ai whoami`验证登录状态。所有命令均向标准输出（stdout）输出JSON。若未全局安装，请在所有命令前添加`npx @cargo-ai/cli`前缀，替代`cargo-ai`。

执行失败的命令会返回非零退出码，并返回`{"errorMessage": "..."}`。

Key concepts

核心概念

Integration: The external service type (e.g. HubSpot, Clearbit, Salesforce). Integrations define what actions are available.
Connector: An authenticated instance of an integration. One integration can have multiple connectors (e.g. two different HubSpot accounts). Connectors are what you reference in workflow node graphs.
Integration（集成）：指外部服务类型（如HubSpot、Clearbit、Salesforce）。集成定义了可用的操作。
Connector（连接器）：集成的已认证实例。一个集成可以拥有多个连接器（例如两个不同的HubSpot账户）。连接器是您在工作流节点图中引用的对象。

Discover resources first

先发现资源

bash
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>                # third-party-specific actions (e.g. HubSpot)
cargo-ai connection native-integration get                # built-in Cargo actions only (NOT third-party)
bash
cargo-ai connection connector list                        # 所有已认证的连接器
cargo-ai connection integration list                      # 所有可用的集成类型
cargo-ai connection integration list --search "hubspot"   # 按名称搜索
cargo-ai connection integration get <slug>                # 第三方服务专属操作（如HubSpot）
cargo-ai connection native-integration get                # 仅内置Cargo操作（非第三方）

integration get
vs 
native-integration get

integration get
与 
native-integration get
对比

These two commands return different sets of actions and are not interchangeable:
CommandWhat it returnsWhen to use
integration get <slug>
Actions specific to a third-party service (e.g. HubSpot contact CRUD, deal management, Salesforce queries)When you need service-specific actions to use in a connector node — use this for HubSpot, Salesforce, Clearbit, etc.
native-integration get
Generic built-in Cargo actions (e.g. HTTP requests, data transforms, internal utilities)When you need Cargo-native capabilities that don't belong to any specific third-party connector
Example: To find HubSpot-specific actions, use 
integration get hubspot
— not 
native-integration get
. The latter will only return generic actions unrelated to HubSpot.
这两个命令返回不同的操作集合，不可互换使用：
命令返回内容使用场景
integration get <slug>
第三方服务专属操作（如HubSpot联系人CRUD、交易管理、Salesforce查询）当您需要在连接器节点中使用服务专属操作时 —— HubSpot、Salesforce、Clearbit等场景请使用此命令
native-integration get
通用内置Cargo操作（如HTTP请求、数据转换、内部工具）当您需要不属于任何特定第三方连接器的Cargo原生功能时
示例：如需查找HubSpot专属操作，请使用
integration get hubspot
—— 而非
native-integration get
。后者仅返回与HubSpot无关的通用操作。

Quick reference

快速参考

bash
cargo-ai connection connector list --integration-slug <slug>
cargo-ai connection connector create --integration-slug <slug> --slug <slug> --name <name>
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 integration list
cargo-ai connection integration get <slug>
cargo-ai connection integration get-documentation <slug>
cargo-ai connection native-integration get
bash
cargo-ai connection connector list --integration-slug <slug>
cargo-ai connection connector create --integration-slug <slug> --slug <slug> --name <name>
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 integration list
cargo-ai connection integration get <slug>
cargo-ai connection integration get-documentation <slug>
cargo-ai connection native-integration get

Connectors

连接器

Connectors are authenticated connections to external services.
bash
undefined
连接器是与外部服务的已认证连接。
bash
undefined

List all connectors

列出所有连接器

cargo-ai connection connector list
cargo-ai connection connector list

Create a connector

创建连接器

cargo-ai connection connector create
--integration-slug clearbit
--slug clearbit_production
--name "Clearbit - Production"
cargo-ai connection connector create
--integration-slug clearbit
--slug clearbit_production
--name "Clearbit - Production"

Update a connector

更新连接器

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

Remove a connector

删除连接器

cargo-ai connection connector remove <connector-uuid>
cargo-ai connection connector remove <connector-uuid>

Check if a connector slug is taken

检查连接器slug是否已被占用

cargo-ai connection connector exists-by-slug --slug clearbit_production

**Note:** Creating a connector requires `--slug` (unique identifier) in addition to `--name` (display name) and `--integration-slug`. For OAuth-based integrations, the authentication flow is completed separately via `connection integration complete-oauth`.
cargo-ai connection connector exists-by-slug --slug clearbit_production

**注意**：创建连接器时，除了`--name`（显示名称）和`--integration-slug`外，还需要`--slug`（唯一标识符）。对于基于OAuth的集成，认证流程需通过`connection integration complete-oauth`单独完成。

Integrations

集成

Integrations define the available services and their connector actions.
bash
undefined
集成定义了可用的服务及其连接器操作。
bash
undefined

List all available integrations

列出所有可用集成

cargo-ai connection integration list
cargo-ai connection integration list

Filter by category

按类别筛选

cargo-ai connection integration list --category enrichment
cargo-ai connection integration list --category enrichment

Search by name

按名称搜索

cargo-ai connection integration list --search "hubspot"
cargo-ai connection integration list --search "hubspot"

Find by exact slug

按精确slug查找

cargo-ai connection integration list --slug clearbit
cargo-ai connection integration list --slug clearbit

Only integrations that have actions (usable in workflow nodes)

仅显示包含操作的集成（可用于工作流节点）

cargo-ai connection integration list --has-actions true
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
cargo-ai connection integration list --has-extractors true

Get built-in Cargo actions and extractors (NOT third-party connector actions)

获取内置Cargo操作和提取器（非第三方连接器操作）

cargo-ai connection native-integration get

**Integration categories:** `engagement`, `marketing`, `sales`, `finance`, `analytics`, `freeform`, `success`, `support`, `enrichment`, `storage`, `custom`.

Use `integration get <slug>` to discover all actions available for a specific third-party service (e.g. HubSpot, Salesforce). Use `native-integration get` only for built-in Cargo actions — it does **not** return HubSpot or other service-specific actions. Actions are referenced by `actionSlug` in workflow node graphs (see the `cargo-orchestration` skill's `references/nodes.md`).
cargo-ai connection native-integration get

**集成类别**：`engagement`（客户互动）、`marketing`（营销）、`sales`（销售）、`finance`（财务）、`analytics`（分析）、`freeform`（自由格式）、`success`（客户成功）、`support`（客户支持）、`enrichment`（数据 enrichment）、`storage`（存储）、`custom`（自定义）。

使用`integration get <slug>`发现特定第三方服务（如HubSpot、Salesforce）的所有可用操作。仅在需要内置Cargo操作时使用`native-integration get` —— 它**不会**返回HubSpot或其他服务专属操作。在工作流节点图中，操作通过`actionSlug`引用（详见`cargo-orchestration`技能的`references/nodes.md`）。

Connector autocomplete — fetching available values for action fields

连接器自动补全 —— 获取操作字段的可用值

Some action fields don't accept freeform input — their allowed values must be fetched dynamically from the connector. When you inspect an action's config (via 
integration get <slug>
or 
native-integration get
), look at the 
uiSchema
alongside the 
jsonSchema
. If a field's 
uiSchema
contains 
"ui:widget": "IntegrationAutocompleteWidget"
, the valid values for that field must be retrieved using 
connector autocomplete
.
部分操作字段不接受自由输入 —— 其允许的值必须从连接器动态获取。当您查看操作配置（通过
integration get <slug>
或
native-integration get
）时，请同时查看
jsonSchema
和
uiSchema
。如果字段的
uiSchema
包含
"ui:widget": "IntegrationAutocompleteWidget"
，则该字段的有效值必须通过
connector autocomplete
命令获取。

How to detect autocomplete fields

如何识别需自动补全的字段

When an action's config looks like this:
json
{
  "jsonSchema": {
    "type": "object",
    "properties": {
      "objectType": { "type": "string", "description": "The object type" }
    }
  },
  "uiSchema": {
    "objectType": {
      "ui:widget": "IntegrationAutocompleteWidget",
      "ui:options": {
        "slug": "listObjects",
        "allowRefresh": true
      }
    }
  }
}
The 
objectType
field requires autocomplete. The 
ui:options.slug
(
"listObjects"
) is the autocomplete slug you pass to 
connector autocomplete
.
当操作配置如下所示时：
json
{
  "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
命令的自动补全slug。

How to call connector autocomplete

如何调用连接器自动补全

bash
cargo-ai connection connector autocomplete \
  --connector-uuid <connector-uuid> \
  --slug <autocomplete-slug> \
  --params '{}'
FlagRequiredDescription
--connector-uuid
yesThe UUID of the connector to autocomplete against
--slug
yesThe autocomplete slug from 
uiSchema[field]["ui:options"].slug
--params
yesJSON object of parameters (use 
{}
when none are needed)
--value
noSearch string to filter results
--refresh
noBypass cache and fetch fresh results
bash
cargo-ai connection connector autocomplete \
  --connector-uuid <connector-uuid> \
  --slug <autocomplete-slug> \
  --params '{}'
参数是否必填说明
--connector-uuid
是用于自动补全的连接器UUID
--slug
是来自
uiSchema[field]["ui:options"].slug
的自动补全slug
--params
是参数JSON对象（无参数时使用
{}
）
--value
否用于筛选结果的搜索字符串
--refresh
否绕过缓存，获取最新结果

Autocomplete with parameters

带参数的自动补全

Some autocomplete fields depend on the value of another field. This is indicated by a 
params
object in 
ui:options
:
json
{
  "uiSchema": {
    "objectType": {
      "ui:widget": "IntegrationAutocompleteWidget",
      "ui:options": { "slug": "listObjects" }
    },
    "propertyName": {
      "ui:widget": "IntegrationAutocompleteWidget",
      "ui:options": {
        "slug": "listObjectProperties",
        "params": { "objectType": "$this.$parent.objectType" }
      }
    }
  }
}
Here, 
propertyName
depends on the selected 
objectType
. Replace the 
$this.$parent...
expression with the actual value you chose:
bash
undefined
部分自动补全字段依赖于其他字段的值，这由
ui:options
中的
params
对象标识：
json
{
  "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...
表达式替换为您选择的实际值：
bash
undefined

1. First, get the list of object types

1. 首先，获取对象类型列表

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

2. Then, get properties for the chosen object type

2. 然后，获取所选对象类型的属性

cargo-ai connection connector autocomplete
--connector-uuid <uuid> --slug listObjectProperties
--params '{"objectType": "contacts"}'
undefined
cargo-ai connection connector autocomplete
--connector-uuid <uuid> --slug listObjectProperties
--params '{"objectType": "contacts"}'
undefined

Response format

响应格式

json
{
  "results": [
    { "label": "Contacts", "value": "contacts" },
    { "label": "Companies", "value": "companies" },
    { "label": "Deals", "value": "deals" }
  ]
}
Use the 
value
field in your node config. The 
label
is the human-readable display name. Results may also include optional 
description
and 
parent
fields.
json
{
  "results": [
    { "label": "Contacts", "value": "contacts" },
    { "label": "Companies", "value": "companies" },
    { "label": "Deals", "value": "deals" }
  ]
}
在节点配置中使用
value
字段。
label
是易于阅读的显示名称。结果还可能包含可选的
description
和
parent
字段。

End-to-end example: configuring a HubSpot action

端到端示例：配置HubSpot操作

bash
undefined
bash
undefined

1. Find your HubSpot connector UUID

1. 查找您的HubSpot连接器UUID

cargo-ai connection connector list --integration-slug hubspot
cargo-ai connection connector list --integration-slug hubspot

2. Get HubSpot actions and inspect their config + uiSchema

2. 获取HubSpot操作并查看其配置及uiSchema

cargo-ai connection integration get hubspot
cargo-ai connection integration get hubspot

→ The "findRecords" action has objectType with autocomplete slug "listObjects"

→ "findRecords"操作的objectType字段带有自动补全slug "listObjects"

3. Fetch available object types

3. 获取可用对象类型

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

→ Returns: contacts, companies, deals, tickets, etc.

→ 返回：contacts、companies、deals、tickets等

4. Fetch properties for the chosen object type

4. 获取所选对象类型的属性

cargo-ai connection connector autocomplete
--connector-uuid <hubspot-connector-uuid>
--slug listObjectProperties
--params '{"objectType": "contacts"}'
cargo-ai connection connector autocomplete
--connector-uuid <hubspot-connector-uuid>
--slug listObjectProperties
--params '{"objectType": "contacts"}'

→ Returns: email, firstname, lastname, phone, etc.

→ 返回：email、firstname、lastname、phone等

5. Use these values in your workflow node config

5. 在工作流节点配置中使用这些值

undefined
undefined

Using connector actions in workflows

在工作流中使用连接器操作

Connector actions are used as nodes in workflow graphs. To use an action:
bash
undefined
连接器操作在工作流图中作为节点使用。使用操作的步骤如下：
bash
undefined

1. Find your connector UUID

1. 查找您的连接器UUID

cargo-ai connection connector list
cargo-ai connection connector list

→ Filter the output by integrationSlug to find the right connector

→ 通过integrationSlug过滤输出来找到正确的连接器

2. Discover available actions for the integration

2. 发现集成的可用操作

cargo-ai connection integration get <integration-slug>
cargo-ai connection integration get <integration-slug>

→ actions are keyed by actionSlug, with config.jsonSchema for each

→ 操作以actionSlug为键，每个操作都有config.jsonSchema

→ Or use get-documentation for a plain text overview

→ 或使用get-documentation获取纯文本概述

→ Or use native-integration get for built-in Cargo actions (not third-party)

→ 或使用native-integration get获取内置Cargo操作（非第三方）

3. Reference the connector and action in a node graph

3. 在节点图中引用连接器和操作

See cargo-orchestration references/nodes.md for the full node syntax

完整节点语法请查看cargo-orchestration references/nodes.md


Example connector node (Clearbit company enrichment):

```json
{
  "uuid": "node-uuid",
  "slug": "enrich",
  "kind": "connector",
  "integrationSlug": "clearbit",
  "actionSlug": "company_enrich",
  "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 }
}

连接器节点示例（Clearbit公司数据 enrichment）：

```json
{
  "uuid": "node-uuid",
  "slug": "enrich",
  "kind": "connector",
  "integrationSlug": "clearbit",
  "actionSlug": "company_enrich",
  "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

帮助

Every command supports 
--help
:
bash
cargo-ai connection connector list --help
cargo-ai connection connector create --help
cargo-ai connection integration list --help
所有命令均支持
--help
参数：
bash
cargo-ai connection connector list --help
cargo-ai connection connector create --help
cargo-ai connection integration list --help