getcargohq/cargo-skills包含需要注意的行为
SKILL DETAIL
cargo-connection
getcargohq/cargo-skills/cargo-connection
cargo-connection 技能用于管理 Cargo 与外部系统之间的连接。它允许你列出已认证的连接器、浏览可用的集成目录，并获取工作流节点所需的 connectorUuid 和 actionSlug。该技能支持多种集成，包括 HubSpot、Salesforce、Clearbit 等，并提供了连接器的创建、更新、删除和自动补全功能。 通过该技能，你可以使用 cargo-ai CLI 命令来管理连接器和集成，例如列出所有连接器、搜索集成、获取特定集成的操作列表，以及为需要动态值的字段获取自动补全选项。技能还提供了详细的示例和参考文档，帮助你配置工作流节点。
安装量 · 160查看来源
Installation
npx skills add https://github.com/getcargohq/cargo-skills --skill cargo-connection
技能文件
SKILL.md
最近同步 · 2026年9月2日
references/examples/connectors.md›
# Connector examples
## List all connectors
```bash
cargo-ai connection connector list
```
## Filter connectors by integration
```bash
cargo-ai connection connector list --integration-slug clearbit
# → Returns only connectors for the Clearbit integration
```
## Get a single connector
```bash
cargo-ai connection connector get <connector-uuid>
# → Returns the full connector object (same shape as an item from connector list)
```
## Find a connector UUID for use in a workflow
```bash
# 1. List connectors (optionally filter by integration)
cargo-ai connection connector list --integration-slug clearbit
# → Extract the "uuid" field from the right connector
# 2. Use the UUID in your workflow node's connectorUuid config
```
## Create a connector
```bash
cargo-ai connection connector create \
--integration-slug clearbit \
--slug clearbit_production \
--name "Clearbit - Production"
```
`--slug` is a unique identifier (no spaces), `--name` is the display name. For credit-based integrations (`useCredits: true`), this is all that's needed. For credential-based integrations, pass `--config` with the integration-specific credentials JSON.
## Update a connector
```bash
cargo-ai connection connector update --uuid <connector-uuid> --name "Clearbit - Staging"
cargo-ai connection connector update --uuid <connector-uuid> --config '{"apiKey":"new-key"}'
```
## Remove a connector
```bash
# Check usage first — list connectors and check playsCount and toolsCount
cargo-ai connection connector list
# → High counts mean the connector is heavily used — remove dependencies before deleting
cargo-ai connection connector remove <connector-uuid>
```
## Check if a slug is available
```bash
cargo-ai connection connector exists-by-slug --slug clearbit_production
# → { "exists": true }
```
## Connector usage audit
Find all connectors and how many plays/tools use each:
```bash
cargo-ai connection connector list
# → Check playsCount and toolsCount fields for each connector
```
## Autocomplete — fetch available values for an action field
When an action's `uiSchema` marks a field with `"ui:widget": "IntegrationAutocompleteWidget"`, use `connector autocomplete` to get the allowed values.
```bash
# Basic autocomplete (no params needed)
cargo-ai connection connector autocomplete \
--connector-uuid <connector-uuid> \
--slug listObjects \
--params '{}'
# → { "results": [{ "label": "Contacts", "value": "contacts" }, ...] }
```
## Autocomplete with dependent parameters
Some fields depend on another field's value. Pass the dependency in `--params`:
```bash
# Get properties for a specific object type
cargo-ai connection connector autocomplete \
--connector-uuid <connector-uuid> \
--slug listObjectProperties \
--params '{"objectType": "contacts"}'
# → { "results": [{ "label": "Email", "value": "email" }, ...] }
```
## Autocomplete with search filtering
Use `--value` to filter results by a search string:
```bash
cargo-ai connection connector autocomplete \
--connector-uuid <connector-uuid> \
--slug listObjectProperties \
--params '{"objectType": "contacts"}' \
--value "email"
# → Returns only properties matching "email"
```
## Autocomplete with cache refresh
Results are cached (default 30 minutes). Use `--refresh` to bypass the cache:
```bash
cargo-ai connection connector autocomplete \
--connector-uuid <connector-uuid> \
--slug listObjects \
--params '{}' \
--refresh
```
## Rate limit awareness
Some connectors have rate limits (visible in the `rateLimit` field from `connector list`):
```bash
cargo-ai connection connector list
# → Check rateLimit.unit (day/hour/minute) and rateLimit.max for each connector
# → Design batches to stay within these limits
```
references/examples/integrations.md›
# Integration examples
## List all available integrations
```bash
cargo-ai connection integration list
```
Response includes `slug`, `name`, `description`, and `category` for each available integration.
## Filter integrations
```bash
# By category
cargo-ai connection integration list --category enrichment
# By name search
cargo-ai connection integration list --search "hubspot"
# By exact slug(s)
cargo-ai connection integration list --slugs clearbit
# Only those with actions (usable in workflow nodes)
cargo-ai connection integration list --has-actions true
# Only those with extractors (can sync data into models)
cargo-ai connection integration list --has-extractors true
```
**Categories:** `engagement`, `marketing`, `sales`, `finance`, `analytics`, `freeform`, `success`, `support`, `enrichment`, `storage`, `custom`.
## Find an integration slug
```bash
cargo-ai connection integration list --search "hubspot"
# → Extract the "slug" value
# → Use slug when creating connectors: --integration-slug <slug>
```
## Get full integration details
```bash
cargo-ai connection integration get clearbit
# → Returns the full integration object with actions, extractors, and configuration schemas
```
Use this to discover all available actions and extractors for an integration, including their `config.jsonSchema` for building workflow nodes.
## Get integration documentation
```bash
cargo-ai connection integration get-documentation clearbit
cargo-ai connection integration get-documentation hubspot
```
Returns plain text documentation for the integration, including available actions and their configuration.
## Discover actions for a specific integration (e.g. HubSpot)
```bash
cargo-ai connection integration get hubspot
# → Returns HubSpot-specific actions (e.g. "create_contact", "update_deal") and extractors
# → Each action includes its config.jsonSchema for building workflow nodes
cargo-ai connection integration get-documentation hubspot
# → Plain text overview of all HubSpot actions
```
**Use `integration get <slug>` when you need service-specific actions** — HubSpot, Salesforce, Clearbit, etc.
## Discover native (built-in Cargo) actions and extractors
```bash
cargo-ai connection native-integration get
# → Returns built-in Cargo actions ONLY — NOT HubSpot or other third-party actions
# → actions: keyed by actionSlug (generic platform utilities)
# → extractors: keyed by extractor slug
```
**Important:** `native-integration get` does **not** return HubSpot-specific or other third-party connector actions. To get those, use `integration get <slug>` instead.
Use `actionSlug` values in workflow node configs (see `cargo-orchestration/references/nodes.md`).
## Set up a connector for use in workflows (full flow)
```bash
# 1. Find the integration slug
cargo-ai connection integration list --search "hubspot"
# → Extract the "slug" value
# 2. Create the connector
cargo-ai connection connector create \
--integration-slug hubspot \
--slug hubspot_production \
--name "HubSpot - Production"
# → Note the returned connector UUID
# 3. Get the integration details to discover available actions
cargo-ai connection integration get hubspot
# → Or get plain text docs: cargo-ai connection integration get-documentation hubspot
# 4. Use the connector UUID and action slug in a workflow node
# See cargo-orchestration references/nodes.md for node syntax
```
## Common integration slugs
| Service | Slug |
| ------------- | -------------- |
| Clearbit | `clearbit` |
| HubSpot | `hubspot` |
| Salesforce | `salesforce` |
| Apollo.io | `apolloio` |
| HTTP (custom) | `http` |
| Slack | `slack` |
| Google Sheets | `googleSheets` |
Run `integration list` for the complete current list.
references/response-shapes.md›
# Response shapes
JSON response structures returned by Cargo CLI commands used in the `cargo-connection` skill.
## cargo-ai connection connector list
```json
{
"connectors": [
{
"uuid": "connector-uuid",
"workspaceUuid": "...",
"userUuid": "...",
"name": "Clearbit - Production",
"slug": "clearbit_production",
"integrationSlug": "clearbit",
"rateLimit": { "unit": "day", "max": 1000 },
"cacheTtlMilliseconds": 86400000,
"playsCount": 2,
"toolsCount": 5,
"modelsCount": 0,
"useCredits": true,
"config": null,
"createdAt": "2025-01-01T00:00:00Z",
"updatedAt": "2025-01-15T00:00:00Z",
"deletedAt": null
}
]
}
```
**Key fields:** `uuid`, `name`, `integrationSlug`, `useCredits`, `playsCount`, `toolsCount`.
When `useCredits` is `true`, actions on this connector consume Cargo credits. When `false`, `config` contains the integration-specific credentials.
## cargo-ai connection connector get
```json
{
"connector": {
"uuid": "connector-uuid",
"workspaceUuid": "...",
"userUuid": "...",
"name": "Clearbit - Production",
"slug": "clearbit_production",
"integrationSlug": "clearbit",
"rateLimit": { "unit": "day", "max": 1000 },
"cacheTtlMilliseconds": 86400000,
"playsCount": 2,
"toolsCount": 5,
"modelsCount": 0,
"useCredits": true,
"config": null,
"createdAt": "2025-01-01T00:00:00Z",
"updatedAt": "2025-01-15T00:00:00Z",
"deletedAt": null
}
}
```
Same shape as a single item from `connector list`.
## cargo-ai connection integration list
Each integration in the list is a full integration object (same shape as `integration get`).
```json
{
"integrations": [
{
"slug": "clearbit",
"name": "Clearbit",
"description": "Company and person enrichment",
"category": "enrichment",
"icon": "https://...",
"color": "#...",
"url": "https://...",
"subCategories": [],
"documentationPath": "...",
"connector": { "config": { "jsonSchema": { ... } } },
"actions": { "enrichCompanyFromDomain": { ... } },
"extractors": {},
"dynamicSchemas": {}
}
]
}
```
**Key fields:** `slug` (used when creating connectors and filtering), `name`, `category`, `actions`, `extractors`.
Supports `--category`, `--slugs`, `--search`, `--has-actions`, `--has-extractors` to filter results.
**Integration categories:** `engagement`, `marketing`, `sales`, `finance`, `analytics`, `freeform`, `success`, `support`, `enrichment`, `storage`, `custom`.
## cargo-ai connection integration get
Returns the full integration object, including all actions and extractors with their configuration schemas.
```json
{
"integration": {
"slug": "clearbit",
"name": "Clearbit",
"description": "Company and person enrichment",
"category": "enrichment",
"icon": "https://...",
"color": "#...",
"url": "https://...",
"subCategories": [],
"documentationPath": "...",
"connector": {
"config": {
"jsonSchema": { "type": "object", "properties": { "apiKey": { "type": "string" } } }
}
},
"actions": {
"enrichCompanyFromDomain": {
"name": "Enrich Company From Domain",
"description": "Enrich a company by domain",
"category": "enrichment",
"icon": "https://...",
"isSerialized": false,
"config": {
"jsonSchema": { "type": "object", "properties": { "domain": { "type": "string" } } }
},
"output": {
"schema": {
"type": "object",
"properties": { "name": { "type": "string" }, "domain": { "type": "string" } }
}
},
"credits": {
"costs": [{ "type": "fixed", "cost": 1 }]
},
"childrenCount": 0
},
"findRecords": {
"name": "Find records",
"description": "Find records matching the given criterias.",
"category": "enrichment",
"icon": "https://...",
"isSerialized": false,
"config": {
"jsonSchema": {
"type": "object",
"properties": {
"objectType": { "type": "string", "description": "The object type" },
"propertyName": { "type": "string", "description": "Property to search on" }
}
},
"uiSchema": {
"objectType": {
"ui:widget": "IntegrationAutocompleteWidget",
"ui:options": {
"slug": "listObjects",
"allowRefresh": true
}
},
"propertyName": {
"ui:widget": "IntegrationAutocompleteWidget",
"ui:options": {
"slug": "listObjectProperties",
"allowRefresh": true,
"params": {
"objectType": "$this.$parent.objectType"
}
}
}
}
},
"credits": {
"costs": [{ "type": "fixed", "cost": 1 }]
},
"childrenCount": 0
}
},
"extractors": {},
"dynamicSchemas": {}
}
}
```
**Key fields:** `actions` is keyed by `actionSlug` — use these in workflow connector nodes. Each action's `config.jsonSchema` is its **input**; `output.schema`, when present, is the JSON Schema of what the action **emits** — read it instead of guessing the output shape (not every action declares one; `integration list` includes it too). `connector.config.jsonSchema` describes the credentials needed when creating a connector (for non-credit integrations). `extractors` is keyed by extractor slug — use these when creating models.
**`uiSchema` and autocomplete:** Each action's `config` may include a `uiSchema` alongside `jsonSchema`. When a field in `uiSchema` has `"ui:widget": "IntegrationAutocompleteWidget"`, its allowed values must be fetched via `connector autocomplete`. The `ui:options.slug` tells you which autocomplete slug to use, and `ui:options.params` (if present) specifies dependent parameters — replace `$this.$parent...` expressions with actual values. See the main SKILL.md for the full autocomplete workflow.
## cargo-ai connection native-integration get
> **Note:** This command returns **built-in Cargo actions only** (e.g. `start`, `end`, `branch`, `filter`, `agent`, `python`). It does **not** return HubSpot, Salesforce, Clearbit, or other third-party connector actions. For those, use `cargo-ai connection integration get <slug>`.
```json
{
"nativeIntegration": {
"actions": {
"send_email": {
"name": "Send Email",
"description": "Send an email via the native Cargo email action",
"category": "enrichment",
"icon": "https://...",
"isSerialized": false,
"config": {
"jsonSchema": { "type": "object", "properties": { "domain": { "type": "string" } } },
"uiSchema": {}
},
"meta": {
"jsonSchema": { "type": "object" }
},
"credits": {
"costs": [{ "type": "fixed", "cost": 1 }]
},
"childrenCount": 0
}
},
"extractors": {
"contacts": {
"name": "Contacts",
"description": "Sync contacts from integration",
"icon": "https://...",
"config": {
"jsonSchema": { "type": "object", "properties": {} },
"uiSchema": {}
},
"mode": {
"kind": "fetch",
"isIncremental": true
}
}
}
}
}
```
**`actions`** is keyed by action slug. Each key is an `actionSlug` for use in workflow connector nodes.
| Field | Description |
| ----- | ----------- |
| `name` | Display name |
| `description` | What the action does |
| `category` | One of: `invisible`, `logic`, `storage`, `ai`, `sales`, `code` |
| `icon` | Icon URL |
| `config.jsonSchema` | JSON Schema describing the action's input parameters |
| `config.uiSchema` | UI hints for each field — check for `IntegrationAutocompleteWidget` to detect autocomplete fields |
| `childrenCount` | Number of child branches (0 for most actions) |
| `credits.costs` | Credit cost per execution. Each cost has `type` (`fixed` or `unit`) and `cost` (number) |
**`extractors`** is keyed by extractor slug. Extractors sync data from an integration into a model.
| Field | Description |
| ----- | ----------- |
| `name` | Display name |
| `description` | What the extractor syncs |
| `icon` | Icon URL |
| `config.jsonSchema` | JSON Schema describing the extractor's configuration |
| `mode.kind` | `"fetch"` (pull-based) or `"ingest"` (push-based) |
| `mode.isIncremental` | Whether the extractor supports incremental sync (fetch mode only) |
## cargo-ai connection connector autocomplete
Fetches the allowed values for a field that uses `IntegrationAutocompleteWidget` in its `uiSchema`.
```json
{
"results": [
{
"label": "Contacts",
"value": "contacts",
"description": "HubSpot contacts object"
},
{
"label": "Companies",
"value": "companies"
},
{
"label": "Deals",
"value": "deals"
}
]
}
```
| Field | Required | Description |
| ----- | -------- | ----------- |
| `label` | yes | Human-readable display name |
| `value` | yes | The value to use in node config |
| `description` | no | Additional context about the option |
| `parent` | no | Parent grouping identifier (for hierarchical options) |
| `configOverride` | no | Additional config values that should be set when this option is selected |
Use the `value` field when setting the corresponding property in a workflow node's `config`.
references/troubleshooting.md›
# Troubleshooting
Common errors and recovery steps for `cargo-connection` commands.
## General
| Symptom | Cause | Fix |
| -------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------- |
| `{"errorMessage": "..."}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |
| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |
| `Unauthorized` or `Forbidden` | Bad or expired credentials | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token <token>`; verify with `cargo-ai whoami` |
## Connectors
| Symptom | Cause | Fix |
| --------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `connector get` returns not found | Wrong UUID | Re-run `connector list` to get the correct UUID |
| `connector create` fails | Integration slug doesn't exist | Run `integration list` to find valid `integrationSlug` values |
| `connector remove` fails | Connector is referenced by active plays or tools | Check `playsCount` and `toolsCount` on the connector; remove or update dependent resources first |
| Workflow fails with connector not found | Connector UUID in node graph is wrong | Re-run `connector list` to verify the UUID used in the node config |
| Action not executing as expected | Wrong `actionSlug` | For third-party connector actions (HubSpot, Salesforce, etc.), run `integration get <slug>` to see correct `actionSlug` values. Only use `native-integration get` for built-in Cargo actions. |
## Connector autocomplete
| Symptom | Cause | Fix |
| ---------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `connector autocomplete` returns empty results | Wrong autocomplete slug or params | Re-check the `uiSchema` from `integration get <slug>` — use the exact `ui:options.slug` and pass required `params` |
| `Invalid autocomplete params` error | Missing or wrong params keys | Check `ui:options.params` in the `uiSchema` — each key listed there must be provided in `--params` with an actual value |
| `connectorNotFound` reason | Wrong connector UUID | Re-run `connector list` to get the correct UUID |
| `failedToGetIntegration` reason | Integration doesn't support autocomplete for this slug | Verify the autocomplete slug exists in the integration's `uiSchema` — not all fields use autocomplete |
| Stale or outdated autocomplete results | Results are cached (default 30 minutes) | Pass `--refresh` to bypass the cache |
| Used a freeform value instead of autocomplete result | Field requires a specific value from the autocomplete result set | Always check `uiSchema` for `IntegrationAutocompleteWidget` — if present, fetch and use a `value` from the autocomplete results |
## Integrations
| Symptom | Cause | Fix |
| ------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| `integration list` doesn't show an expected integration | Integration may not be available in your region or plan | Contact Cargo support or check the integrations page in the app |
| Third-party actions (e.g. HubSpot) not found via `native-integration get` | `native-integration get` only returns built-in Cargo actions | Use `integration get <slug>` (e.g. `integration get hubspot`) to get service-specific actions |
| OAuth flow incomplete | `complete-oauth` not called after creating an OAuth connector | Complete the OAuth flow through the Cargo app UI or via the API |
skill-metadata.json›
{
"$comment": "Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .",
"name": "cargo-connection",
"version": "1.4.0",
"documents": [
{
"path": "SKILL.md",
"kind": "entrypoint",
"title": "Cargo CLI — Connections"
},
{
"path": "references/examples/connectors.md",
"kind": "example",
"title": "Connector examples"
},
{
"path": "references/examples/integrations.md",
"kind": "example",
"title": "Integration examples"
},
{
"path": "references/response-shapes.md",
"kind": "reference",
"title": "Response shapes"
},
{
"path": "references/troubleshooting.md",
"kind": "reference",
"title": "Troubleshooting"
}
],
"contentHash": "f13696973045922b006b9665a679d99fd8fb2ed5463a9c4fd3012f0e7eb171f8"
}
SKILL.md›
---
name: cargo-connection
description: "Connect Cargo to an external system and find out what it can do — authenticate connectors, browse the integration catalog, and resolve the `connectorUuid` and `actionSlug` a workflow node needs. Triggers: \"connect my HubSpot\", \"is Salesforce connected\", \"what integrations do you support\", \"can Cargo talk to <tool>\", \"what actions does <provider> have\", \"I need the connector UUID\", \"set up the API key for\", \"it is asking for credentials again\", \"why is this connector failing auth\", \"list my connectors\". Integrations: amplemarket, amplitude, attio, bigQuery, calendly, closecom, contrast, csv, customerio, dbt, emailBison, expandi, googleAds, googleSheets, heyReach, http, hubspot, hubspotMcp, instantly, instantlyV2, intercom, jira, kitt, lemlist, lgm, linkedinAds, linkedinMatchedAudience, livestorm, manus, marketo, metabase, microsoftTeams, mixpanel, netsuite, netsuiteSoap, notionMcp, octave, onesignal, outreach, pipedrive, postgresql, redshift, resend, rift, salesforce, salesforceMcp, salesloft, Sendgrid, sillage, slack, smartlead, snowflake, sql, stripe, and 83 more. Skip when: choosing between enrichment providers for a GTM job — use cargo-gtm and its provider playbooks."
version: "1.4.0"
compatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token
homepage: https://github.com/getcargohq/cargo-skills
metadata:
author: getcargo
openclaw:
requires:
bins:
- cargo-ai
install:
- kind: node
package: "@cargo-ai/cli@latest"
bins:
- cargo-ai
homepage: https://github.com/getcargohq/cargo-skills
---
# Cargo CLI — Connections
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.
## Bootstrap
Already signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.
```bash
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
```
Every command prints JSON to stdout; failures exit non-zero with `{"errorMessage": "..."}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface.
## 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.
## Discover resources first
**Looking for an action? Search for it — don't browse the catalog.** Two keyword
searches cover the whole surface, and both beat paging `integration list` or
reading a whole `integration get` payload:
```bash
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 category
# and by "is it paid" — which `action list` cannot.
```
Reach for the catalog commands when you need the *integration*, not an action —
its auth fields, its extractors, or the full input schema of an action you have
already picked:
```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> # one integration's actions + input schemas
cargo-ai connection native-integration get # built-in Cargo actions only (NOT third-party)
```
### Which action search?
| | `orchestration action list` | `connection action search` |
|---|---|---|
| Covers | connector, native, **tools, agents** | connector catalog only |
| Returns | a runnable `action` object with `connectorUuid`, workspace connectors, `credits`, autocompletes | `integrationSlug` + `actionSlug`, category, `credits` — you assemble the action yourself |
| Filters | `--kind`, `--integration-slug`, `--limit` | `--category`, `--integration`, **`--credits-only`**, `--limit` |
| Needs | CLI ≥ 1.0.66 | CLI ≥ 1.0.36 |
Default to `action list` — it is the one that hands you something you can execute.
Switch to `action search` for the two questions it alone answers: *which paid
actions match this?* (`--credits-only`) and *what does this category offer?*
(`--category`). Both rank an action-slug or name hit above an integration hit,
above a description hit, and require **all** query terms to match.
### `integration get` vs `native-integration get`
These two commands return **different sets of actions** and are not interchangeable:
| Command | Third-party service actions (HubSpot, Salesforce, Clearbit, …) | Built-in Cargo actions (HTTP, transforms, utilities) | When to use |
|---|---|---|---|
| `integration get <slug>` | ✓ | ✗ | You need actions for a specific third-party service — **use this for HubSpot, Salesforce, Clearbit, etc.** |
| `native-integration get` | ✗ | ✓ | 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` — `native-integration get` will not return them.
## 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
```
## Connectors
Connectors are authenticated connections to external services.
```bash
# List all connectors
cargo-ai connection connector list
# Create a connector
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"
# 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
```
**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`.
## Integrations
Integrations define the available services and their connector actions.
```bash
# 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
```
**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`).
## 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`.
### 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`.
### How to call connector autocomplete
```bash
cargo-ai connection connector autocomplete \
--connector-uuid <connector-uuid> \
--slug <autocomplete-slug> \
--params '{}'
```
| Flag | Required | Description |
| ------------------ | -------- | ----------------------------------------------------------------- |
| `--connector-uuid` | yes | The UUID of the connector to autocomplete against |
| `--slug` | yes | The autocomplete slug from `uiSchema[field]["ui:options"].slug` |
| `--params` | yes | JSON object of parameters (use `{}` when none are needed) |
| `--value` | no | Search string to filter results |
| `--refresh` | no | Bypass cache and fetch fresh results |
### 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
# 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"}'
```
### 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.
### End-to-end example: configuring a HubSpot action
```bash
# 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
```
## Using connector actions in workflows
Connector actions are used as nodes in workflow graphs. To use an action:
```bash
# 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.jsonSchema (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
```
### Reading an action's input schema — and where the inputs go
An action's **input** fields live at `actions.<slug>.config.schema` in the `integration get <slug>` output (`config.jsonSchema` is the same schema decorated for the form UI). Read it before calling an action — don't guess field names.
```bash
# the required input fields for an action:
cargo-ai connection integration get linkedin \
| jq '.integration.actions.connectProfile.config.schema'
# → required: linkedinProfileUrl, identityIds
```
Two footguns:
- **For a top-level action (`action execute` / `execute-batch`), the input values go in `--data`, NOT in the action's `config`.** The fields described by `config.schema` are the `--data` payload; the action definition carries no `config` key at all. **Misplacing them is no longer a loud failure:** older backends rejected the call with `A top-level action does not use action.config; pass the action's inputs via data instead.`, newer ones drop `config` on the way in and run the action with **no inputs at all** — you get a missing-required-field error from the provider, or an empty result, not a message about `config`. If an action comes back empty for no obvious reason, check that the inputs are in `--data`. (Inside a workflow **node graph** those same fields go in the node's `config` — see `cargo-orchestration/references/nodes.md`. The "`--data`, not `config`" rule is specific to `action execute`/`execute-batch`.)
- **Some inputs must be resolved first via autocomplete.** If a field's `uiSchema` carries `IntegrationAutocompleteWidget`, fetch its values with `connector autocomplete` (above). Notably, LinkedIn engagement/extraction actions (`connectProfile`, `visitProfile`, `extractEventAttendees`, `extractProfileViewers`) require `identityIds` — the connected account that *acts* — resolved via the `listIdentityIds` autocomplete. A `must match format "uuid"` error means that identity is missing.
Example connector node (Clearbit company enrichment):
```json
{
"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
Every command supports `--help`:
```bash
cargo-ai connection connector list --help
cargo-ai connection connector create --help
cargo-ai connection integration list --help
```