Cargo CLI Overview

The Cargo CLI gives you programmatic, terminal-level access to every part of the Cargo platform — models, connectors, workflows, agents, billing, and workspace administration.

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.

This is the imperative way to work with Cargo — one-off, scripted commands. For managing a whole workspace as versioned code, use the declarative CDK (cargo-ai cdk, which ships in this same binary); for driving these commands with natural language, use Skills. See CLI, CDK & Skills for how the three fit together.

---

Installation

Install from npm and authenticate once — the same login the CDK and Skills reuse. The Quickstart has the full walkthrough (install, login, whoami, workspace targeting, and CI token setup):

npm install -g @cargo-ai/cli && cargo-ai login --token <your-api-token>

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

---

Command domains

The CLI is organized into command groups — run cargo-ai --help for the full list, and cargo-ai <group> --help to drill in. The primary domains:

Command group	Area	What it does
cargo-ai orchestration	Runtime	Run tools on single records, trigger batch plays across segments, inspect runs/batches/spans/traces
cargo-ai storage	Schema	Inspect model DDL, create and update columns (custom, computed, metric, lookup), manage datasets, set model relationships
cargo-ai connection	Connectors	Authenticate connector instances, list available integrations and their action slugs, discover native actions
cargo-ai ai	Agents	Create and configure agents, manage releases (draft → deploy), chat with agents, connect MCP servers, inspect memories
cargo-ai segmentation	Segments	List segments, fetch and download segment records with filters and sorts
cargo-ai billing	Costs	Track credit consumption by workflow, connector, or agent; check subscription status; view invoices
cargo-ai workspaceManagement	Admin	Invite users, create and rotate API tokens, organize resources into folders, manage roles
cargo-ai cdk	Declarative	Plan, deploy, refresh, and destroy a CDK workspace
cargo-ai manifest	Framework	Scaffold a Manifest GTM repo and install cookbook modules into it

Other groups include content, context, system-of-record, revenue-organization, hosting, and expression.

Cargo Skills package these domains into prompt bundles so an AI agent can operate them from natural language — same commands, driven by an agent. See Skills.

How the domains 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, run get-metrics --release-uuid
folderUuid	workspaceManagement 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, skipped
Batch	batch create	batch get <uuid> every 5s	success, error, cancelled, skipped
Agent message	message create	message get <uuid> every 2s	done when finishedAt is set

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 print JSON to stderr:

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

API errors additionally include status and body fields with the HTTP response details.

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.

Tools

Define runnable automations in code with defineTool and defineWorkflow.

Agents

Wire up an AI agent with defineAgent — tools, models, and sub-agents.