Cargo CLI Overview - Cargo Documentation

The @cargo-ai/cli package mirrors the full Cargo platform surface as structured shell commands. Every response is JSON, every failure exits non-zero, and every asynchronous operation (runs, batches, agent messages) has a corresponding polling command. This makes the CLI a natural fit for automation pipelines, CI/CD workflows, and AI agents that need to operate Cargo without opening a browser. The CLI is also the foundation of Cargo Skills — structured prompt packages that teach AI agents (Claude, GPT-4o, Gemini) exactly how to use it.

Installation

npm install -g @cargo-ai/cli

cargo-ai login --token <your-api-token>

To target a specific workspace:

cargo-ai login --token <your-api-token> --workspace-uuid <your-workspace-uuid>

Verify:

cargo-ai whoami
# → {"user":{"uuid":"...","email":"you@example.com"},"workspace":{"uuid":"...","name":"My Workspace"}}

Without a global install, prefix every command with npx @cargo-ai/cli instead of cargo-ai.

API token values are shown only once at creation time. Store them immediately in a secrets manager (GitHub Secrets, AWS Secrets Manager, 1Password, etc.).

The seven skills

The CLI is organized into seven domains. Each domain maps to a dedicated Cargo Skill that any AI agent can load to operate that part of the platform.

Skill	Domain	What it does
`cargo-cli-orchestration`	Runtime	Run tools on single records, trigger batch plays across segments, chat with AI agents, query the data warehouse with SQL, fetch live segment data
`cargo-cli-storage`	Schema	Inspect model DDL, create and update columns (custom, computed, metric, lookup), manage datasets, set model relationships
`cargo-cli-connection`	Connectors	Authenticate connector instances, list available integrations and their action slugs, discover native actions
`cargo-cli-ai`	Agents	Create and configure agents, manage releases (draft → deploy), upload files for RAG, connect MCP servers, inspect memories
`cargo-cli-analytics`	Measurement	Download run results, export segment data to files, pull per-node error rates and success metrics
`cargo-cli-billing`	Costs	Track credit consumption by workflow, connector, or agent; check subscription status; view invoices
`cargo-cli-workspace`	Admin	Invite users, create and rotate API tokens, organize resources into folders, manage roles

How the skills relate

Key concepts

Plays vs. Tools

	Play	Tool
Trigger	Segment-driven (reactive)	On-demand (proactive)
Run command	`batch create`	`run create` or `batch create`
Batch data kinds	`segment`, `change`, `filter`, `recordIds`	`file`, `records`

Using run create on a play’s workflowUuid returns a playNotCompatible error. Plays must always use batch create.

UUID discovery sequence

Most commands require UUIDs. Always discover them before acting:

cargo-ai whoami                              # confirm workspace
cargo-ai orchestration play list             # → workflowUuid, segmentUuid
cargo-ai orchestration tool list             # → workflowUuid
cargo-ai storage model list                  # → modelUuid
cargo-ai storage model get-ddl <model-uuid>  # → exact SQL table name
cargo-ai connection connector list           # → connectorUuid
cargo-ai ai agent list                       # → agentUuid
cargo-ai segmentation segment list           # → segmentUuid

UUID flow table

UUID	Produced by	Consumed by
`workflowUuid`	`play list` / `tool list`	`run create`, `batch create`, metrics
`modelUuid`	`storage model list`	`segment fetch`, `segment download`, SoR DDL
`segmentUuid`	`segmentation segment list`	`batch create --data '{"kind":"segment",...}'`
`agentUuid`	`ai agent list`	`ai chat create`, agent nodes in workflows
`connectorUuid`	`connection connector list`	Connector nodes in workflows, billing filter
`actionSlug`	`connection integration get`	Connector nodes in workflows
`batchUuid`	`batch create`	`batch get`, `batch download`, run filter
`releaseUuid`	`batch get`	`release get`, `batch download`
`folderUuid`	`workspace folder list`	`play/tool/agent update --folder-uuid`

Async operations

All runs, batches, and agent messages are async. Either use --wait-until-finished to block until completion, or poll manually:

Operation	Create	Poll	Terminal statuses
Run	`run create`	`run get <uuid>` every 2s	`success`, `error`, `cancelled`
Batch	`batch create`	`batch get <uuid>` every 5s	`success`, `error`, `cancelled`
Agent message	`message create`	`message get <uuid>` every 2s	`success`, `error`

Filter syntax

Filters use a two-level structure with conjonction (not conjunction — this is intentional and silent if misspelled):

{
  "conjonction": "and",
  "groups": [
    {
      "conjonction": "and",
      "conditions": [
        {
          "kind": "string",
          "columnSlug": "country",
          "operator": "is",
          "values": ["US"]
        },
        {
          "kind": "number",
          "columnSlug": "employee_count",
          "operator": "greaterThan",
          "value": 100
        }
      ]
    }
  ]
}

Operators by column type:

Type	Available operators
`string`	`is`, `isNot`, `contains`, `doesNotContain`, `startsWith`, `endsWith`, `isNull`, `isNotNull`, `isEmpty`, `isNotEmpty`
`number`	`is`, `isNot`, `greaterThan`, `lowerThan`, `between`, `isNull`, `isNotNull`
`date`	`is`, `isNot`, `greaterThan`, `lowerThan`, `between`, `isNull`, `isNotNull`
`boolean`	`isTrue`, `isFalse`, `isNull`, `isNotNull`
`object` / `array`	`isNull`, `isNotNull`, `matchConditions`

Error handling

All failed commands exit non-zero and return:

{ "errorMessage": "Human-readable description of what went wrong" }

To add automatic retries to connector nodes in a workflow, include a retry block in the node definition:

"retry": {
  "maximumAttempts": 3,
  "initialInterval": 1000,
  "backoffCoefficient": 2
}

Common gotchas

Gotcha	Rule
Filter spelling	Always write `conjonction`, never `conjunction`. Typo fails silently.
`run create` vs `batch create`	`run create` is tool-only. Use `batch create` for plays.
Segment fetch flag	`segment fetch` and `segment download` require `--model-uuid`, not `--segment-uuid`.
DDL before SQL	Run `model get-ddl <uuid>` first — table names look like `datasets_default.models_companies`.
Token security	API token values are shown once. Store immediately.
Invoice amounts	`subscription get-invoices` returns amounts in cents. Divide by 100 for dollars.
Batch partial failure	`status: success` on a batch can still contain individual run failures — always check `failedRunsCount`.
Rate limits	Only `kind: "connector"` nodes have rate limits. Native nodes do not. Ramp in stages: 1 → 50 → 500 → 1000+.

Next steps

Cargo Skills

Install Cargo Skills and drive your entire workspace with natural language prompts.

API Reference

Use the REST API directly for programmatic integrations beyond the CLI.

Build a tool

Create your first automation workflow in the Cargo UI.

Build an agent

Configure an AI agent with tools, files, and memory.

CLI & Skills

Documentation Index

​Installation

​The seven skills

​How the skills relate

​Key concepts

​Plays vs. Tools

​UUID discovery sequence

​UUID flow table

​Async operations

​Filter syntax

​Error handling

​Common gotchas

​Next steps

Cargo Skills

API Reference

Build a tool

Build an agent

Installation

The seven skills

How the skills relate

Key concepts

Plays vs. Tools

UUID discovery sequence

UUID flow table

Async operations

Filter syntax

Error handling

Common gotchas

Next steps