Update to Cargo CLI

{
  "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\". 138 integrations including HubSpot, Salesforce, Attio, Pipedrive, Outreach, Salesloft, Slack, Snowflake, BigQuery, Postgres, Stripe, and Google/LinkedIn ad audiences. Skip when: choosing between enrichment providers for a GTM job — use cargo-gtm and its provider playbooks.",
  "included_files": [
    {
      "relative_path": "references/examples/connectors.md",
      "size_in_bytes": 3769
    },
    {
      "relative_path": "references/examples/integrations.md",
      "size_in_bytes": 3830
    },
    {
      "relative_path": "references/response-shapes.md",
      "size_in_bytes": 9677
    },
    {
      "relative_path": "references/troubleshooting.md",
      "size_in_bytes": 5493
    },
    {
      "relative_path": "skill-metadata.json",
      "size_in_bytes": 921
    }
  ],
  "skill_md_contents": "---\nname: cargo-connection\ndescription: \"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\\\". 138 integrations including HubSpot, Salesforce, Attio, Pipedrive, Outreach, Salesloft, Slack, Snowflake, BigQuery, Postgres, Stripe, and Google/LinkedIn ad audiences. Skip when: choosing between enrichment providers for a GTM job — use cargo-gtm and its provider playbooks.\"\nversion: \"1.4.0\"\ncompatibility: 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\nhomepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Connections\n\nConnector and integration management: listing connectors, discovering available integrations, and managing authenticated connector instances.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/connectors.md` for connector CRUD and discovery examples.\n> See `references/examples/integrations.md` for listing available integrations and OAuth flows.\n> 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.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write\n```\n\nEvery 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.\n\n## Key concepts\n\n**Integration:** The external service type (e.g. HubSpot, Clearbit, Salesforce). Integrations define what actions are available.\n\n**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.\n\n## Discover resources first\n\n**Looking for an action? Search for it — don't browse the catalog.** Two keyword\nsearches cover the whole surface, and both beat paging `integration list` or\nreading a whole `integration get` payload:\n\n```bash\ncargo-ai orchestration action list <query>                # START HERE — connector + native + tools + agents.\n                                                          # Returns a ready-to-run action object (connectorUuid\n                                                          # resolved) and the action's credit costs.\ncargo-ai connection action search <query> --credits-only  # connector catalog only, but filters by category\n                                                          # and by \"is it paid\" — which `action list` cannot.\n```\n\nReach for the catalog commands when you need the *integration*, not an action —\nits auth fields, its extractors, or the full input schema of an action you have\nalready picked:\n\n```bash\ncargo-ai connection connector list                        # all authenticated connectors\ncargo-ai connection integration list                      # all available integration types\ncargo-ai connection integration list --search \"hubspot\"   # search by name\ncargo-ai connection integration get <slug>                # one integration's actions + input schemas\ncargo-ai connection native-integration get                # built-in Cargo actions only (NOT third-party)\n```\n\n### Which action search?\n\n| | `orchestration action list` | `connection action search` |\n|---|---|---|\n| Covers | connector, native, **tools, agents** | connector catalog only |\n| Returns | a runnable `action` object with `connectorUuid`, workspace connectors, `credits`, autocompletes | `integrationSlug` + `actionSlug`, category, `credits` — you assemble the action yourself |\n| Filters | `--kind`, `--integration-slug`, `--limit` | `--category`, `--integration`, **`--credits-only`**, `--limit` |\n| Needs | CLI ≥ 1.0.66 | CLI ≥ 1.0.36 |\n\nDefault to `action list` — it is the one that hands you something you can execute.\nSwitch to `action search` for the two questions it alone answers: *which paid\nactions match this?* (`--credits-only`) and *what does this category offer?*\n(`--category`). Both rank an action-slug or name hit above an integration hit,\nabove a description hit, and require **all** query terms to match.\n\n### `integration get` vs `native-integration get`\n\nThese two commands return **different sets of actions** and are not interchangeable:\n\n| Command | Third-party service actions (HubSpot, Salesforce, Clearbit, …) | Built-in Cargo actions (HTTP, transforms, utilities) | When to use |\n|---|---|---|---|\n| `integration get <slug>` | ✓ | ✗ | You need actions for a specific third-party service — **use this for HubSpot, Salesforce, Clearbit, etc.** |\n| `native-integration get` | ✗ | ✓ | You need Cargo-native capabilities that don't belong to any specific third-party connector |\n\n**Example:** To find HubSpot-specific actions, use `integration get hubspot` — `native-integration get` will not return them.\n\n## Quick reference\n\n```bash\ncargo-ai connection connector list --integration-slug <slug>\ncargo-ai connection connector create --integration-slug <slug> --slug <slug> --name <name>\ncargo-ai connection connector update --uuid <uuid> --name <name>\ncargo-ai connection connector remove <connector-uuid>\ncargo-ai connection connector get <connector-uuid>\ncargo-ai connection connector autocomplete --connector-uuid <uuid> --slug <slug> --params '<json>'\ncargo-ai connection integration list\ncargo-ai connection integration get <slug>\ncargo-ai connection integration get-documentation <slug>\ncargo-ai connection native-integration get\n```\n\n## Connectors\n\nConnectors are authenticated connections to external services.\n\n```bash\n# List all connectors\ncargo-ai connection connector list\n\n# Create a connector\ncargo-ai connection connector create \\\n  --integration-slug clearbit \\\n  --slug clearbit_production \\\n  --name \"Clearbit - Production\"\n\n# Update a connector\ncargo-ai connection connector update --uuid <connector-uuid> --name \"Clearbit - Staging\"\n\n# Remove a connector\ncargo-ai connection connector remove <connector-uuid>\n\n# Check if a connector slug is taken\ncargo-ai connection connector exists-by-slug --slug clearbit_production\n```\n\n**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`.\n\n## Integrations\n\nIntegrations define the available services and their connector actions.\n\n```bash\n# List all available integrations\ncargo-ai connection integration list\n\n# Filter by category\ncargo-ai connection integration list --category enrichment\n\n# Search by name\ncargo-ai connection integration list --search \"hubspot\"\n\n# Find by exact slug(s)\ncargo-ai connection integration list --slugs clearbit\n\n# Only integrations that have actions (usable in workflow nodes)\ncargo-ai connection integration list --has-actions true\n\n# Only integrations that have extractors (can sync data into models)\ncargo-ai connection integration list --has-extractors true\n\n# Get built-in Cargo actions and extractors (NOT third-party connector actions)\ncargo-ai connection native-integration get\n```\n\n**Integration categories:** `engagement`, `marketing`, `sales`, `finance`, `analytics`, `freeform`, `success`, `support`, `enrichment`, `storage`, `custom`.\n\nUse `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`).\n\n## Connector autocomplete — fetching available values for action fields\n\nSome 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`.\n\n### How to detect autocomplete fields\n\nWhen an action's config looks like this:\n\n```json\n{\n  \"jsonSchema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"objectType\": { \"type\": \"string\", \"description\": \"The object type\" }\n    }\n  },\n  \"uiSchema\": {\n    \"objectType\": {\n      \"ui:widget\": \"IntegrationAutocompleteWidget\",\n      \"ui:options\": {\n        \"slug\": \"listObjects\",\n        \"allowRefresh\": true\n      }\n    }\n  }\n}\n```\n\nThe `objectType` field requires autocomplete. The `ui:options.slug` (`\"listObjects\"`) is the autocomplete slug you pass to `connector autocomplete`.\n\n### How to call connector autocomplete\n\n```bash\ncargo-ai connection connector autocomplete \\\n  --connector-uuid <connector-uuid> \\\n  --slug <autocomplete-slug> \\\n  --params '{}'\n```\n\n| Flag               | Required | Description                                                       |\n| ------------------ | -------- | ----------------------------------------------------------------- |\n| `--connector-uuid` | yes      | The UUID of the connector to autocomplete against                 |\n| `--slug`           | yes      | The autocomplete slug from `uiSchema[field][\"ui:options\"].slug`   |\n| `--params`         | yes      | JSON object of parameters (use `{}` when none are needed)         |\n| `--value`          | no       | Search string to filter results                                   |\n| `--refresh`        | no       | Bypass cache and fetch fresh results                              |\n\n### Autocomplete with parameters\n\nSome autocomplete fields depend on the value of another field. This is indicated by a `params` object in `ui:options`:\n\n```json\n{\n  \"uiSchema\": {\n    \"objectType\": {\n      \"ui:widget\": \"IntegrationAutocompleteWidget\",\n      \"ui:options\": { \"slug\": \"listObjects\" }\n    },\n    \"propertyName\": {\n      \"ui:widget\": \"IntegrationAutocompleteWidget\",\n      \"ui:options\": {\n        \"slug\": \"listObjectProperties\",\n        \"params\": { \"objectType\": \"$this.$parent.objectType\" }\n      }\n    }\n  }\n}\n```\n\nHere, `propertyName` depends on the selected `objectType`. Replace the `$this.$parent...` expression with the actual value you chose:\n\n```bash\n# 1. First, get the list of object types\ncargo-ai connection connector autocomplete \\\n  --connector-uuid <uuid> --slug listObjects --params '{}'\n\n# 2. Then, get properties for the chosen object type\ncargo-ai connection connector autocomplete \\\n  --connector-uuid <uuid> --slug listObjectProperties \\\n  --params '{\"objectType\": \"contacts\"}'\n```\n\n### Response format\n\n```json\n{\n  \"results\": [\n    { \"label\": \"Contacts\", \"value\": \"contacts\" },\n    { \"label\": \"Companies\", \"value\": \"companies\" },\n    { \"label\": \"Deals\", \"value\": \"deals\" }\n  ]\n}\n```\n\nUse the `value` field in your node config. The `label` is the human-readable display name. Results may also include optional `description` and `parent` fields.\n\n### End-to-end example: configuring a HubSpot action\n\n```bash\n# 1. Find your HubSpot connector UUID\ncargo-ai connection connector list --integration-slug hubspot\n\n# 2. Get HubSpot actions and inspect their config + uiSchema\ncargo-ai connection integration get hubspot\n# → The \"findRecords\" action has objectType with autocomplete slug \"listObjects\"\n\n# 3. Fetch available object types\ncargo-ai connection connector autocomplete \\\n  --connector-uuid <hubspot-connector-uuid> \\\n  --slug listObjects --params '{}'\n# → Returns: contacts, companies, deals, tickets, etc.\n\n# 4. Fetch properties for the chosen object type\ncargo-ai connection connector autocomplete \\\n  --connector-uuid <hubspot-connector-uuid> \\\n  --slug listObjectProperties \\\n  --params '{\"objectType\": \"contacts\"}'\n# → Returns: email, firstname, lastname, phone, etc.\n\n# 5. Use these values in your workflow node config\n```\n\n## Using connector actions in workflows\n\nConnector actions are used as nodes in workflow graphs. To use an action:\n\n```bash\n# 1. Find your connector UUID\ncargo-ai connection connector list\n# → Filter the output by integrationSlug to find the right connector\n\n# 2. Discover the action — search first, and only then read its schema\ncargo-ai orchestration action list <keywords> --integration-slug <integration-slug>\ncargo-ai connection integration get <integration-slug>\n# → actions are keyed by actionSlug, with config.jsonSchema (input) for each\n# → many actions also carry output.schema — the JSON Schema of what the action\n#   emits; use it to wire downstream nodes instead of guessing (absent on some actions)\n# → Or use get-documentation for a plain text overview\n# → Or use native-integration get for built-in Cargo actions (not third-party)\n\n# 3. Reference the connector and action in a node graph\n# See cargo-orchestration references/nodes.md for the full node syntax\n```\n\n### Reading an action's input schema — and where the inputs go\n\nAn 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.\n\n```bash\n# the required input fields for an action:\ncargo-ai connection integration get linkedin \\\n  | jq '.integration.actions.connectProfile.config.schema'\n# → required: linkedinProfileUrl, identityIds\n```\n\nTwo footguns:\n\n- **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`.)\n- **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.\n\nExample connector node (Clearbit company enrichment):\n\n```json\n{\n  \"uuid\": \"node-uuid\",\n  \"slug\": \"enrich\",\n  \"kind\": \"connector\",\n  \"integrationSlug\": \"clearbit\",\n  \"actionSlug\": \"enrichCompany\",\n  \"connectorUuid\": \"<clearbit-connector-uuid>\",\n  \"config\": {\n    \"domain\": {\n      \"kind\": \"templateExpression\",\n      \"expression\": \"{{nodes.start.domain}}\",\n      \"instructTo\": \"none\",\n      \"fromRecipe\": false\n    }\n  },\n  \"childrenUuids\": [\"end-node-uuid\"],\n  \"fallbackOnFailure\": false,\n  \"position\": { \"x\": 0, \"y\": 166 }\n}\n```\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai connection connector list --help\ncargo-ai connection connector create --help\ncargo-ai connection integration list --help\n```\n"
}