cargo-connection

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

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

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

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

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

---
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
```