Cargo Connection

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.

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.

Prerequisites

See `../cargo/references/prerequisites.md` for install, login (--oauth / --token), JSON output conventions, and error shapes. Verify the session with cargo-ai whoami before running any of the commands below.

Discover resources first

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)

integration get vs native-integration get

These two commands return different sets of actions and are not interchangeable:

Example: To find HubSpot-specific actions, use integration get hubspot — native-integration get will not return them.

Quick reference

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.

# 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.

# 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
cargo-ai connection integration list --slug 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:

{
  "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

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

Autocomplete with parameters

Some autocomplete fields depend on the value of another field. This is indicated by a params object in ui:options:

{
  "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:

# 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

{
  "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

# 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:

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

# 2. Discover available actions for the integration
cargo-ai connection integration get <integration-slug>
# → actions are keyed by actionSlug, with config.jsonSchema for each
# → 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

Example connector node (Clearbit company enrichment):

{
  "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:

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

Connector examples

List all connectors

cargo-ai connection connector list

Filter connectors by integration

cargo-ai connection connector list --integration-slug clearbit
# → Returns only connectors for the Clearbit integration

Get a single connector

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

# 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

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

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

# 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

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:

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.

# 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:

# 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:

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:

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):

cargo-ai connection connector list
# → Check rateLimit.unit (day/hour/minute) and rateLimit.max for each connector
# → Design batches to stay within these limits

Integration examples

List all available integrations

cargo-ai connection integration list

Response includes slug, name, description, and category for each available integration.

Filter integrations

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

# By name search
cargo-ai connection integration list --search "hubspot"

# By exact slug
cargo-ai connection integration list --slug 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

cargo-ai connection integration list --search "hubspot"
# → Extract the "slug" value
# → Use slug when creating connectors: --integration-slug <slug>

Get full integration details

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

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)

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

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)

# 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

Run integration list for the complete current list.

Response shapes

JSON response structures returned by Cargo CLI commands used in the cargo-connection skill.

cargo-ai connection connector list

{
  "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

{
  "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).

{
  "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, --slug, --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.

{
  "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" } } }
        },
        "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. 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>.

{
  "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.

`extractors` is keyed by extractor slug. Extractors sync data from an integration into a model.

cargo-ai connection connector autocomplete

Fetches the allowed values for a field that uses IntegrationAutocompleteWidget in its uiSchema.

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

Use the value field when setting the corresponding property in a workflow node's config.

Troubleshooting

Common errors and recovery steps for cargo-connection commands.

General

Connectors

Connector autocomplete

Integrations