cargo-skills

██████    ████    █████    ██████   ██████
██    ░  ██  ██░  ██  ██   ██    ░  ██  ██░
██       ██████░  █████ ░  ██ ███   ██  ██░
██       ██  ██░  ██ ██    ██  ██░  ██  ██░
██████   ██  ██░  ██  ██   ██████░  ██████░
 ░░░░░░   ░░  ░░   ░░  ░░   ░░░░░░   ░░░░░░

Cargo CLI — Skills Overview

This repository contains seven skills for the Cargo AI-native revenue infrastructure. Each skill covers a distinct domain. This file tells you which skill to load for any given task and how to combine them.

Installation

npm install -g @cargo-ai/cli
cargo-ai login --token <your-api-token>
# Optional: target a specific workspace
cargo-ai login --token <your-api-token> --workspace-uuid <uuid>
# Verify
cargo-ai whoami

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

All commands output JSON to stdout. Failed commands exit non-zero and return {"errorMessage": "..."}.

When the CLI fails or you're stuck — send a workspace management report

Whenever the CLI is failing in a way the skill references and --help cannot resolve, the user or agent is repeatedly retrying the same command without progress, the syntax for a flag / JSON payload is unclear, or a needed capability seems missing — escalate by submitting a report to workspace management:

cargo-ai workspace report create \
  --title "<one-line summary of the problem>" \
  --description "<exact command(s) tried, errorMessage, expected vs actual, UUIDs involved>"

Trigger conditions (any one is enough):

• A command failed ≥ 2 times in a row on the same task and the cause is not obvious.
• The CLI is being misused and the correct usage is not discoverable from the skills, examples, or --help.
• A documented behavior contradicts what you observe.
• A feature appears to be missing entirely.

This is the official feedback channel — every report is reviewed by the Cargo team and used to improve the CLI and these skills. Do not give up silently — file a report. See cargo-workspace-management/SKILL.md (Reports section) and cargo-workspace-management/references/examples/reports.md for templates.

---

Skills at a glance

Skill	Load when you need to…
cargo-orchestration	Execute actions, run workflows, trigger batches, chat with agents, query your data warehouse
cargo-analytics	Download run results, export segment data, monitor error rates and metrics
cargo-billing	Check credit usage, view subscription details, track costs per workflow or connector
cargo-storage	Inspect or modify data models, columns, datasets, and relationships
cargo-connection	Manage connector authentication, discover available integrations and their actions
cargo-ai	Create and configure agents, upload files for RAG, manage MCP servers
cargo-workspace-management	Invite users, create API tokens, organize folders, manage roles, report CLI issues to management

---

How the skills relate

┌──────────────────────────────────────────────────────────────┐
│                  cargo-workspace-management                  │
│             Authentication, users, tokens, folders           │
└──────────────────────────────────────────────────────────────┘

  ┌─────────────────┐   ┌────────────────────┐   ┌─────────────────┐
  │  cargo-storage  │   │  cargo-connection  │   │    cargo-ai     │
  │ Models, columns,│   │ Connectors,        │   │ Agents, files,  │
  │ datasets        │   │ integration actions│   │ MCP servers     │
  └────────┬────────┘   └─────────┬──────────┘   └────────┬────────┘
           │                      │  (UUIDs flow down)    │
           └──────────────────────┼───────────────────────┘
                                  ▼
             ┌───────────────────────────────────────┐
             │          cargo-orchestration          │
             │   Runs, batches, plays, tools, SoR    │
             └───────────────┬───────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
 ┌────────────────────────┐  ┌───────────────────────────┐
 │    cargo-analytics     │  │       cargo-billing       │
 │  Results, metrics,     │  │    Credit usage, costs    │
 │  exports               │  │                           │
 └────────────────────────┘  └───────────────────────────┘

Dependency rules in practice:

• cargo-workspace-management provides auth context for every skill — set it up first.
• cargo-storage, cargo-connection, and cargo-ai are peer skills that supply UUIDs to cargo-orchestration. They don't depend on each other.
• Before querying via system-of-record, load cargo-storage to get the DDL (exact table name).
• Before building a workflow node graph, load cargo-connection to get connectorUuid and actionSlug.
• Before executing a workflow that uses an agent node, load cargo-ai to get agentUuid.
• After runs complete, load cargo-analytics to download results or measure performance.
• Load cargo-billing to understand credit consumption for any of the above.

---

Skill details

cargo-orchestration

The execution hub. Execute actions, run workflows, chat with AI agents, query your data warehouse, and fetch segment records.

Key commands:

# Single actions (no workflow needed)
cargo-ai orchestration action execute --action '{"kind":"tool","toolUuid":"<uuid>","config":{}}' --data '{...}'
cargo-ai orchestration action execute-batch --action '{"kind":"connector","integrationSlug":"...","actionSlug":"...","config":{}}' --records '[{...},{...}]'

# Workflows (chain multiple actions)
cargo-ai orchestration run create --workflow-uuid <uuid> --data '{...}'
cargo-ai orchestration run create --data '{...}' --nodes '[...]'
cargo-ai orchestration batch create --workflow-uuid <uuid> --data '{"kind":"segment","segmentUuid":"..."}'

# AI agents
cargo-ai ai message create --chat-uuid <uuid> --parts '[{"type":"text","text":"..."}]'

# Data
cargo-ai system-of-record client query "SELECT * FROM <table> LIMIT 10"
cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'

Critical rules:

• See the decision flowchart at the top of cargo-orchestration/SKILL.md for when to use action execute vs run create vs batch create.
• Filter JSON uses conjonction (not conjunction) — breaks silently if misspelled.
• Always get DDL before querying the system-of-record: cargo-ai storage model get-ddl <model-uuid>.
• All operations are async — poll or pass --wait-until-finished. See Async polling.

References: cargo-orchestration/SKILL.md

---

cargo-analytics

Measurement and export. Use to download run results, export segment data, and monitor error rates and success metrics.

Key commands:

cargo-ai orchestration run get-metrics --workflow-uuid <uuid>
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished
cargo-ai orchestration run count --workflow-uuid <uuid> --statuses error
cargo-ai segmentation segment download --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'

Critical rules:

• segment download requires --model-uuid, not --segment-uuid.
• For batch result download, get the output-node-slug from release get <release-uuid> → nodes[].slug.
• For billing and credit usage, use cargo-billing instead.

References: cargo-analytics/SKILL.md

---

cargo-billing

Cost and credit management. Use to track credit consumption per workflow, connector, or agent, check subscription status, and view invoices.

Key commands:

cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD>
cargo-ai billing usage get-metrics --from <date> --to <date> --group-by workflow_uuid
cargo-ai billing subscription get
cargo-ai billing subscription get-invoices

Critical rules:

• Requires a token with admin access.
• Invoice amounts are in cents — divide by 100 for dollars.
• subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount from subscription get = remaining credits.

References: cargo-billing/SKILL.md

---

cargo-storage

Data schema management. Use to inspect models, create or update columns, navigate datasets, and understand your workspace's data structure.

Key commands:

cargo-ai storage model list
cargo-ai storage model get-ddl <model-uuid>   # always run before SoR queries
cargo-ai storage column list --model-uuid <uuid>
cargo-ai storage relationship set --from-model-uuid <uuid> --to-model-uuid <uuid>

Critical rules:

• Always run model get-ddl before querying via system-of-record — it contains the exact table name (e.g. datasets_default.models_companies).
• For advanced record queries (filtering, sorting, pagination), use segmentation segment fetch from cargo-orchestration.

References: cargo-storage/SKILL.md

---

cargo-connection

Connector and integration management. Use to authenticate external services, discover what actions they support, and get the connectorUuid and actionSlug values needed for workflow node graphs.

Key commands:

cargo-ai connection connector list
cargo-ai connection integration list
cargo-ai connection integration get <slug>          # third-party actions (HubSpot, Salesforce, etc.)
cargo-ai connection native-integration get          # built-in Cargo actions only (NOT third-party)

Key concepts:

• Integration = external service type (HubSpot, Clearbit, Salesforce, …)
• Connector = authenticated instance of an integration (referenced by connectorUuid in nodes)

References: cargo-connection/SKILL.md

---

cargo-ai

Agent resource management. Use to create and configure agents, upload documents for retrieval-augmented generation (RAG), and connect MCP servers.

For using agents (sending messages, multi-turn chat, polling), use cargo-orchestration.

Key commands:

cargo-ai ai agent list
cargo-ai ai agent create --name "Lead Researcher" --language-model-slug gpt-4o --temperature 0.3
cargo-ai ai file upload --file-path ./knowledge-base.pdf
cargo-ai ai mcp-server create --name "Internal Tools" --url "https://..."
cargo-ai ai memory list --agent-uuid <uuid>

See cargo-ai/SKILL.md for model and temperature guidance by use case.

References: cargo-ai/SKILL.md

---

cargo-workspace-management

Workspace administration. Use to invite users, create and rotate API tokens, organize plays/tools/agents into folders, manage roles, and submit reports to workspace management when the CLI fails or is being misused.

Key commands:

cargo-ai whoami
cargo-ai workspace user create --user-email [email protected] --role-slug <slug>
cargo-ai workspace token create --name "CI/CD pipeline"
cargo-ai workspace folder create --name "Q1 Campaigns" --emoji-slug "rocket" --kind "play"
cargo-ai workspace report create --title "<summary>" --description "<details>"

Critical rules:

• Most commands require a token with admin access.
• workspace token create requires --name (the legacy --from-user flag was removed). Pick a name that makes the token's purpose obvious in token list later.
• Token values are only shown once at creation — store immediately in a secrets manager (GitHub Secrets, AWS Secrets Manager, etc.).
• Always send a workspace report create when the CLI errors, is being used incorrectly, or you (user or agent) are struggling to make progress on a CLI task — see the section at the top of this file and cargo-workspace-management/references/examples/reports.md.

References: cargo-workspace-management/SKILL.md

---

Async polling

All operations are asynchronous. Pass --wait-until-finished to block, or poll:

Result type	Poll command	Interval	Terminal when
Run	cargo-ai orchestration run get <uuid>	2s	status is success, error, or cancelled
Batch	cargo-ai orchestration batch get <uuid>	5s	status is success, error, or cancelled
Agent message	cargo-ai ai message get <uuid>	2s	status is success or error

action execute returns a run; action execute-batch returns a batch — same polling applies.

See cargo-orchestration/references/polling.md for retry strategies, error handling, and large-batch guidance.

---

UUID flow between skills

Most cargo-orchestration operations require UUIDs from other skills. This table maps which skill produces each UUID and which commands consume it.

UUID	Produced by	Consumed by
workflowUuid	orchestration play list / tool list	run create, batch create, run get-metrics, run download
modelUuid	storage model list	segment fetch, segment download, system-of-record query (via DDL)
segmentUuid	segmentation segment list	batch create --data '{"kind":"segment",...}'
agentUuid	ai agent list	ai chat create, node graph (kind: "agent")
connectorUuid	connection connector list	Node graph (kind: "connector"), billing usage --connector-uuid
actionSlug	connection integration get <slug> (third-party) or connection native-integration get (built-in)	Node graph (kind: "connector" or kind: "native")
releaseUuid	orchestration batch get → .releaseUuid	orchestration release get, batch download
batchUuid	orchestration batch create	batch get, batch download, run get-metrics --batch-uuid
folderUuid	workspace folder list	play list --folder-uuid, tool list --folder-uuid
roleSlug	workspace role list	workspace user create --role-slug

Standard discovery sequence before running a workflow:

# 1. Confirm identity
cargo-ai whoami

# 2. Find the tool or play to run
cargo-ai orchestration tool list
cargo-ai orchestration play list

# 3. Find the model and get its DDL (if querying via SoR)
cargo-ai storage model list
cargo-ai storage model get-ddl <model-uuid>

# 4. Find connectors needed by the workflow nodes
cargo-ai connection connector list

# 5. Find agents used in workflow nodes
cargo-ai ai agent list

# 6. Find the segment to process (for plays / batch with segment data)
cargo-ai segmentation segment list

Retrieve in the UI

Each resource has a dedicated page in the Cargo app. Use these URL patterns to cross-reference a UUID returned by the CLI with the UI, or to extract a UUID from a URL the user pastes.

Resource	URL pattern
Play	app.getcargo.io/workspaces/<WORKSPACE_UUID>/plays/<PLAY_UUID>
Tool	app.getcargo.io/workspaces/<WORKSPACE_UUID>/tools/<TOOL_UUID>
Agent	app.getcargo.io/workspaces/<WORKSPACE_UUID>/agents/<AGENT_UUID>
Model	app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>

The workspace UUID is returned by cargo-ai whoami under workspace.uuid.

---

End-to-end use cases

1. Enrich a single company (simplest path)

Skills needed: cargo-orchestration

1. orchestration action execute            → run a connector action on one record
   --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"company_enrich","config":{}}'
   --data '{"domain":"acme.com"}' --wait-until-finished

2. Enrich a list of companies and push to CRM

Skills needed: cargo-storage, cargo-connection, cargo-orchestration, cargo-analytics

1. storage model get-ddl                   → get exact table name
2. connection connector list               → get enrichment + CRM connector UUIDs
3. connection integration get <slug>       → discover third-party action slugs (e.g. HubSpot, Clearbit)
4. orchestration tool list                 → find the enrichment tool
5. orchestration batch create      → run on a segment of companies
6. orchestration batch get         → poll until status is terminal
7. analytics run download          → export results

3. Score leads with AI and update the model

Skills needed: cargo-ai, cargo-orchestration, cargo-billing

1. ai agent list                   → find or create the scoring agent
2. ai agent create                 → configure instructions, model, temperature 0.0
3. orchestration play list         → find the scoring play
4. orchestration batch create      → trigger on a segment of new leads
5. orchestration batch get         → poll until status is terminal
6. billing usage get-metrics       → check credit consumption

4. Build a custom enrichment workflow from scratch

Skills needed: cargo-connection, cargo-orchestration

1. connection connector list               → get connector UUID
2. connection integration get <slug>       → get actionSlug for the third-party service
3. orchestration node validate --nodes     → validate graph before running
4. orchestration run create --nodes        → run with custom node graph
5. orchestration run get                   → poll to terminal state

5. Monitor workflow health and alert on errors

Skills needed: cargo-orchestration, cargo-analytics

1. orchestration tool list / play list    → discover workflowUuid
2. analytics run count --statuses error   → count errors in period
3. analytics run get-metrics              → get success/error rate breakdown
4. analytics run download --statuses error → download failed runs for inspection

6. Bootstrap a fresh workspace

Skills needed: cargo-workspace-management, cargo-storage, cargo-connection, cargo-ai

1. workspace token create --name <label>   → create a dedicated, named API token
2. workspace role list             → discover available roles
3. workspace user create           → invite team members
4. storage model create            → create Companies and Contacts models
5. storage column create           → add columns (name, domain, employee_count, etc.)
6. storage relationship set        → link Contacts → Companies
7. connection connector create     → connect enrichment and CRM integrations
8. ai agent create                 → configure an AI agent for research or scoring
9. workspace folder create         → organize plays and tools into folders

7. Export and analyze segment data

Skills needed: cargo-storage, cargo-analytics

1. storage model list              → get modelUuid
2. analytics segment download      → export with filter and sort
   --filter '{"conjonction":"and","groups":[
     {"conjonction":"and","conditions":[
       {"kind":"string","columnSlug":"country","operator":"is","values":["US"]}
     ]}
   ]}'
   --sort '[{"columnSlug":"created_at","kind":"desc"}]'

---

Common gotchas

Gotcha	Detail
conjonction spelling	Filter JSON uses conjonction (not conjunction). This is intentional. A typo here fails silently — no records returned.
run create vs batch create	run create only works with tool workflows. Using a play's workflowUuid returns playNotCompatible.
--model-uuid vs --segment-uuid	segment fetch and segment download require --model-uuid. Get it from segment list → .modelUuid.
DDL before SQL	Never guess table names. Always run model get-ddl <uuid> first. Table names look like datasets_default.models_companies.
Token shown once	API token values are only returned at creation. Store immediately. workspace token create requires --name (no more --from-user).
Invoice amounts in cents	subscription get-invoices returns amount in cents. Divide by 100.
Plays vs tools	Play = reacts to data changes (segment-driven). Tool = triggered on demand (manual, API, cron).
Batch data kinds	Play workflows accept: segment, change, filter, recordIds. Tool workflows accept: file, records.
Third-party connector rate limits	Only kind: "connector" nodes (Clearbit, HubSpot, etc.) have rate limits — native nodes do not. Errors grow silently as the batch runs. Start at 1 record, then 50, then 500 before full-scale. Add retry with backoff to connector nodes.