Skip to main content
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
Log in with your API token (find it under Settings > API in your Cargo workspace): 
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.
SkillDomainWhat it does
cargo-cli-orchestrationRuntimeRun 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-storageSchemaInspect model DDL, create and update columns (custom, computed, metric, lookup), manage datasets, set model relationships
cargo-cli-connectionConnectorsAuthenticate connector instances, list available integrations and their action slugs, discover native actions
cargo-cli-aiAgentsCreate and configure agents, manage releases (draft → deploy), upload files for RAG, connect MCP servers, inspect memories
cargo-cli-analyticsMeasurementDownload run results, export segment data to files, pull per-node error rates and success metrics
cargo-cli-billingCostsTrack credit consumption by workflow, connector, or agent; check subscription status; view invoices
cargo-cli-workspaceAdminInvite users, create and rotate API tokens, organize resources into folders, manage roles

​
How the skills relate

​
Key concepts

​
Plays vs. Tools

PlayTool
TriggerSegment-driven (reactive)On-demand (proactive)
Run commandbatch createrun create or batch create
Batch data kindssegment, change, filter, recordIdsfile, 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

UUIDProduced byConsumed by
workflowUuidplay list / tool listrun create, batch create, metrics
modelUuidstorage model listsegment fetch, segment download, SoR DDL
segmentUuidsegmentation segment listbatch create --data '{"kind":"segment",...}'
agentUuidai agent listai chat create, agent nodes in workflows
connectorUuidconnection connector listConnector nodes in workflows, billing filter
actionSlugconnection integration getConnector nodes in workflows
batchUuidbatch createbatch get, batch download, run filter
releaseUuidbatch getrelease get, batch download
folderUuidworkspace folder listplay/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:
OperationCreatePollTerminal statuses
Runrun createrun get <uuid> every 2ssuccess, error, cancelled
Batchbatch createbatch get <uuid> every 5ssuccess, error, cancelled
Agent messagemessage createmessage get <uuid> every 2ssuccess, 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:
TypeAvailable operators
stringis, isNot, contains, doesNotContain, startsWith, endsWith, isNull, isNotNull, isEmpty, isNotEmpty
numberis, isNot, greaterThan, lowerThan, between, isNull, isNotNull
dateis, isNot, greaterThan, lowerThan, between, isNull, isNotNull
booleanisTrue, isFalse, isNull, isNotNull
object / arrayisNull, 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

GotchaRule
Filter spellingAlways write conjonction, never conjunction. Typo fails silently.
run create vs batch createrun create is tool-only. Use batch create for plays.
Segment fetch flagsegment fetch and segment download require --model-uuid, not --segment-uuid.
DDL before SQLRun model get-ddl <uuid> first — table names look like datasets_default.models_companies.
Token securityAPI token values are shown once. Store immediately.
Invoice amountssubscription get-invoices returns amounts in cents. Divide by 100 for dollars.
Batch partial failurestatus: success on a batch can still contain individual run failures — always check failedRunsCount.
Rate limitsOnly 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.