> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

```bash theme={null}
npm install -g @cargo-ai/cli
```

Log in with your API token (find it under **Settings > API** in your Cargo workspace):

```bash theme={null}
cargo-ai login --token <your-api-token>
```

To target a specific workspace:

```bash theme={null}
cargo-ai login --token <your-api-token> --workspace-uuid <your-workspace-uuid>
```

Verify:

```bash theme={null}
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`.

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

***

## 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

```mermaid theme={null}
graph TD
    workspace["<b>cargo-cli-workspace</b><br/>Authentication, users, tokens, folders"]

    storage["<b>cargo-cli-storage</b><br/>Models, columns, datasets"]
    connection["<b>cargo-cli-connection</b><br/>Connectors, integration actions"]
    ai["<b>cargo-cli-ai</b><br/>Agents, files, MCP servers"]

    orchestration["<b>cargo-cli-orchestration</b><br/>Runs, batches, plays, tools, SoR"]

    analytics["<b>cargo-cli-analytics</b><br/>Results, metrics, exports"]
    billing["<b>cargo-cli-billing</b><br/>Credit usage, costs, invoices"]

    workspace --- storage
    workspace --- connection
    workspace --- ai

    storage -- "UUIDs flow down" --> orchestration
    connection --> orchestration
    ai --> orchestration

    orchestration --> analytics
    orchestration --> billing
```

***

## 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`              |

<Warning>
  Using `run create` on a play's `workflowUuid` returns a `playNotCompatible`
  error. Plays must always use `batch create`.
</Warning>

### UUID discovery sequence

Most commands require UUIDs. Always discover them before acting:

```bash theme={null}
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):

```json theme={null}
{
  "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:

```json theme={null}
{ "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:

```json theme={null}
"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

<CardGroup cols={2}>
  <Card title="Cargo Skills" icon="robot" href="/cli/skills">
    Install Cargo Skills and drive your entire workspace with natural language
    prompts.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Use the REST API directly for programmatic integrations beyond the CLI.
  </Card>

  <Card title="Build a tool" icon="wrench" href="/get-started/build-a-tool">
    Create your first automation workflow in the Cargo UI.
  </Card>

  <Card title="Build an agent" icon="sparkles" href="/get-started/build-an-agent">
    Configure an AI agent with tools, files, and memory.
  </Card>
</CardGroup>