> ## 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. 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](/get-started/project-layout) (`cargo-ai cdk`, which ships in this same binary); for driving these commands with natural language, use [Skills](/skills/overview). See [CLI, CDK & Skills](/get-started/cli-cdk-and-skills) for how the three fit together. *** ## Installation Install from npm and authenticate once — the same login the CDK and Skills reuse. The [Quickstart](/get-started/quickstart) has the full walkthrough (install, `login`, `whoami`, workspace targeting, and CI token setup): ```bash theme={null} npm install -g @cargo-ai/cli && cargo-ai login --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 --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](/get-started/project-layout) | | `cargo-ai manifest` | Framework | Scaffold a [Manifest GTM repo](/cli/manifest) 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](/skills/overview). ### How the domains relate ```mermaid theme={null} graph TD workspace["workspaceManagement
Authentication, users, tokens, folders"] storage["storage
Models, columns, datasets"] connection["connection
Connectors, integration actions"] ai["ai
Agents, files, MCP servers"] orchestration["orchestration
Runs, batches, plays, tools"] billing["billing
Credit usage, costs, invoices"] workspace --- storage workspace --- connection workspace --- ai storage -- "UUIDs flow down" --> orchestration connection --> orchestration ai --> orchestration 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` | 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: ```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 # → 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 ` every 2s | `success`, `error`, `cancelled`, `skipped` | | Batch | `batch create` | `batch get ` every 5s | `success`, `error`, `cancelled`, `skipped` | | Agent message | `message create` | `message get ` 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): ```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 print JSON to stderr: ```json theme={null} { "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: ```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 ` 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 Install Cargo Skills and drive your entire workspace with natural language prompts. Use the REST API directly for programmatic integrations beyond the CLI. Define runnable automations in code with `defineTool` and `defineWorkflow`. Wire up an AI agent with `defineAgent` — tools, models, and sub-agents.