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.

Bootstrap

Already signed in (cargo-ai whoami returns a workspace)? Skip to the next section.

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email you@company.com  # 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` 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:

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:

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)

Deprecated integrations still appear in the catalog. integration list returns them with isDeprecated: true and a display name ending in (deprecated). Existing connectors keep working — deprecation breaks nothing — but never wire a new workflow to one. Two were deprecated in CLI 1.0.92, the self-referential cargo integration among them. Read the flag rather than keeping a list: check isDeprecated before proposing any integration you found by browsing instead of by action list.

Which action search?

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:

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