Cargo

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

Cargo CLI — Skills Overview

This repository contains 11 skills at the repo root: one outcome skill (cargo-gtm) and ten capability skills.

• `cargo-gtm` — application library. The front door for any GTM task ("build a TAM list", "find 5 fintech CTOs", "monitor job changes"). Routes via internal recipes (../cargo-gtm/recipes/*.md) and provider playbooks (../cargo-gtm/provider-playbooks/*.md).
• Capability skills — standard library. One per CLI domain (orchestration, storage, connection, AI, content, context, analytics, billing, hosting, workspace management). Loaded by cargo-gtm, or directly when you need a specific CLI domain.

cargo-gtm delegates to capability skills; capability skills never reference cargo-gtm (one-way dependency).

Glossary: See `references/glossary.md` for term-by-term definitions (UUIDs, slugs, conjonction, run/batch/play/tool, signal/persona/ICP, etc.).

Installation

npm install -g @cargo-ai/cli
cargo-ai login --oauth                                   # browser sign-in (recommended)
# or: cargo-ai login --token <your-api-token>            # use an existing workspace-scoped API token
# Optional: pin a default workspace at login
cargo-ai login --oauth --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": "..."}. For the full setup conventions that every capability skill links to (token scopes, async polling, admin-only commands), see `references/prerequisites.md`.

Every Cargo session has three jobs

Automated by the Cargo installer. Jobs 1 and 3 (refresh + session register/finalize) run on their own when the SessionStart + Stop + SessionEnd hooks scaffolded by curl -fsSL https://api.getcargo.io/install.sh | sh are present. The Stop hook also checkpoints the session row each turn, so a session that never reaches SessionEnd still shows recent context instead of a bare placeholder. Do these by hand only when the hooks aren't installed. Job 2 (reporting) is always your responsibility — it can't be automated.

1. At session start — refresh and register

Before any other Cargo command, refresh the CLI and skills, then register the session in workspace management:

# Refresh — idempotent, ~10s
npm install -g @cargo-ai/cli@latest
npx -y skills add getcargohq/cargo-skills

# Register the session (placeholders OK — overwritten at session end)
cargo-ai workspaceManagement session upsert \
  --session-id <claude-session-id> \
  --title "Claude Code session <claude-session-id>" \
  --summary "Session in progress."

Skip the refresh only if the user explicitly pinned a version. Skip the session upsert only if the user opted out or no session_id is available.

2. Mid-session — re-refresh, or escalate when stuck

Re-refresh the CLI and skills mid-session when:

• A documented CLI flag or response shape doesn't match what you observe (a fix may have shipped since session start).
• The user explicitly asks ("bump cargo", "make sure I'm on latest").

Send a workspace management report when 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:

cargo-ai workspaceManagement 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.

3. At session end — finalize the session row

Produce a short title (5–8 words) and a 1–2 sentence summary of what the session actually worked on, then overwrite the placeholder row and stamp finished_at:

cargo-ai workspaceManagement session upsert \
  --session-id <claude-session-id> \
  --title "<5-8 word title>" \
  --summary "<1-2 sentence summary of what was accomplished or attempted>" \
  --finished

--title and --summary are required (NOT NULL). --finished stamps finished_at = now; pass --finished-at <iso> for an explicit timestamp.

---

Skills at a glance

Outcome skill

Load when the user states a real-world goal.

Capability skills

Load for a specific CLI domain. The first link in each row jumps to the actual SKILL.md; the parenthetical jumps to the recap on this page.

Agent knowledge for RAG: files + libraries live in the content domain → `cargo-content`; how they attach to an agent → `cargo-ai`. (Files/libraries moved out of the old ai file … path in CLI ≥ 1.0.19.)

CLI domains without a dedicated skill yet

The CLI exposes several domains that no capability skill wraps yet. Reach for them directly (cargo-ai <domain> --help) when a task needs them, and file a workspaceManagement report if the surface is unclear:

---

How the skills relate

            ┌─────────────────────────────────────┐
            │              cargo-gtm              │
            │   Outcome / front door for GTM      │
            │   Recipes, guides, provider-playbks │
            └─────────────────┬───────────────────┘
                              │ delegates to ↓ (one-way)
       ┌──────────────────────┴──────────────────────┐
       │                                             │
┌──────────────────────────────────────────────────────────────┐
│              cargo-workspace-management                      │
│         Authentication, users, tokens, folders               │
└──────────────────────────────────────────────────────────────┘

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

             ┌───────────────────────────────────────┐
             │             cargo-context             │
             │  Git-backed GTM markdown knowledge:   │
             │  personas, plays, proof, signals…     │
             └───────────────────────────────────────┘
           (orthogonal: not part of the workflow flow)

Dependency rules in practice:

• cargo-gtm delegates to capability skills via relative paths (../cargo-orchestration/...). Capability skills never reference cargo-gtm.
• 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.
• cargo-content owns workspace files and libraries (the content domain). It produces file/library UUIDs that cargo-ai consumes as agent release resources (RAG). Uploaded content files also surface read-only under .files/ in the cargo-context runtime sandbox.
• cargo-context is orthogonal to the workflow-execution flow. It touches the git-backed GTM knowledge base (markdown/MDX), not storage or workflow runs. Use it for capturing/editing the workspace's prose context — personas, plays, proof, objections, signals — and for inspecting the typed knowledge graph.
• For SQL queries against storage, use cargo-ai storage query execute "<sql>" (tables as <datasetSlug>.<modelSlug>). Load cargo-storage to discover dataset and model slugs, and to fetch the DDL when you need column types or the SQL dialect.
• For SQL queries against orchestration runtime tables (runs, batches, spans, records) — error rates, per-node failures, time-series — use cargo-ai orchestration query execute "<sql>". Workspace scoping is automatic; tables are referenced without a schema prefix.
• 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. For action output retrieval, prefer `cargo-ai orchestration run download-outputs` over `run download` — the former returns a signed-URL CSV/JSON of just the output node's data.
• Load cargo-billing to understand credit consumption for any of the above.

---

Skill details

cargo-gtm

The outcome skill — front door for any GTM task. Bundles routing (SKILL.md), phase guides (guides/), scenario recipes (recipes/), per-provider playbooks (provider-playbooks/), references (references/), and a sub-agent (agents/).

Recipes shipped:

Priority provider stack (recipes lead with these): salesNavigator (sourcing), cargo native (firmographics + signals), waterfall (multi-source enrichment + email verify + job-change), FullEnrich (premium contact lookup), theirStack (tech-stack + hiring intent), peopleDataLabs (heavyweight backfill).

Critical rules:

• All recipes use credits-based actions (cargo-ai connection integration list → 141 credits-based actions across 120 integrations).
• Action shape: {"kind":"connector","integrationSlug":"<slug>","actionSlug":"<slug>","config":{}} — no `connectorUuid` in `config`.
• Output retrieval: cargo-ai orchestration run download-outputs --output-node-slug <slug> (NOT run download).
• peopleDataLabs filter shape: searchX uses cargo's {conjonction, groups, conditions} shape; queryX takes a PDL SQL string — never Elasticsearch.

References: ../cargo-gtm/SKILL.md

---

cargo-orchestration

The execution hub. Execute actions, run workflows, chat with AI agents, query orchestration runtime tables (runs/batches/spans/records) with SQL, and fetch segment records.

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.
• Prefer built-in actions + expressions when building a node graph. Avoid python, script (JS), and raw HTTP nodes unless necessary: use variables for transforms, the native agent node for LLM calls, the integration's dedicated connector action for APIs, and branch/filter/switch for routing. See ../cargo-orchestration/references/node-selection.md.
• Filter JSON uses conjonction (not conjunction) — breaks silently if misspelled.
• Query orchestration runtime tables (ClickHouse) with cargo-ai orchestration query execute "<sql>" against runs, batches, spans, records (no schema prefix; workspace scoping is automatic).
• For SQL against workspace storage (Companies, Contacts, …), use cargo-ai storage query execute "<sql>" — documented in cargo-storage.
• All operations are async — poll or pass --wait-until-finished. See Async polling.

References: ../cargo-orchestration/SKILL.md

---

cargo-analytics

Measurement and export. Download run results, export segment data, and monitor error rates and success metrics.

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. Track credit consumption per workflow, connector, or agent; check subscription status; view 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 and SQL queries. Inspect models, create or update columns, navigate datasets, understand workspace data structure, and run SQL against workspace storage.

Critical rules:

• Query via cargo-ai storage query execute "<sql>" (or storage query download --query "<sql>" for full exports) using <datasetSlug>.<modelSlug> table names (e.g. default.companies). model get-ddl is optional — useful for column types and SQL dialect.
• For SQL against orchestration runtime tables (runs/batches/spans/records), use cargo-ai orchestration query execute "<sql>" — documented in cargo-orchestration.
• 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. Authenticate external services, discover supported actions, get the connectorUuid and actionSlug values needed for workflow node graphs.

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. Create and configure agents, configure releases, attach knowledge for retrieval-augmented generation (RAG), connect MCP servers, manage memories.

Critical rules:

• Knowledge for RAG attaches to an agent via the release's resources: files + libraries come from `cargo-content`. Wire them in with release update-draft --resources … then release deploy-draft.
• CLI ≥ 1.0.19: files and libraries moved out of the ai domain into the top-level `content` domain (now the cargo-content skill). The old cargo-ai ai file … commands no longer exist.

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

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

References: ../cargo-ai/SKILL.md

---

cargo-content

Workspace knowledge files & libraries. Upload, list, rename, move, and remove files (PDFs, CSVs, text); create and sync libraries — native (workspace-managed) or connector-backed (synced from an external source via an unstructured-data extractor). These are the RAG knowledge resources agents reference.

Critical rules:

• New top-level `content` domain in CLI ≥ 1.0.19 — cargo-ai content file … / cargo-ai content library …. The old cargo-ai ai file … path is gone (unknown command → you're on the old path; bump the CLI).
• A file or library is inert until attached to an agent's deployed release resources — that wiring lives in `cargo-ai`.
• Uploaded content files are also readable (read-only) under .files/ in the cargo-context runtime sandbox.
• For batch-run input files (CSVs that drive a batch), use cargo-ai workspaceManagement file upload (a different surface) — see cargo-workspace-management.

References: ../cargo-content/SKILL.md

---

cargo-context

GTM context repository. Browse, read, write, and edit the workspace's git-backed knowledge base of typed markdown/MDX files — personas, plays, proof, objections, signals, ICPs, etc. — via the runtime sandbox. Inspect cross-references with the knowledge graph.

Key concepts:

• Context repository = the GitHub repo backing the workspace's context. Canonical example: `getcargohq/cargo-workspaces`. Files use kebab-case.md names, YAML frontmatter with required title + description, and domain/slug cross-refs (no .md).
• Runtime sandbox = a checked-out, executable copy of the context repo. runtime write and runtime edit push to the default branch; runtime execute does not push.
• Knowledge graph = the typed graph over every md/mdx file, with frontmatter and outbound cross-refs per node. Built via cargo-ai context graph get.

Critical rules:

• runtime write / runtime edit commit and push. runtime execute is ephemeral — use it for grep/ls/inspection, never for persistent changes.
• runtime edit --old-string must match the file content exactly once. Read first, copy whitespace verbatim.
• Set title + description frontmatter on every .md/.mdx file — a strong convention, not enforced: missing/malformed frontmatter is still committed, it just indexes poorly (graph falls back to filename + first paragraph, and reads summary, not description).
• Graph edges form only from frontmatter references:, markdown links, or wikilinks — a bare path in prose creates no edge. Cite source files in references:.
• For domains, conventions, and per-domain templates, see ../cargo-context/references/conventions.md.

Lifecycle:

• For bootstrapping a fresh workspace's context from a domain (ICP, personas, proof, signals — idempotent, skips already-seeded domains), see `../cargo-context/references/examples/bootstrap-from-domain.md`.
• For the full bootstrap + ongoing call-driven refresh playbook (Phase 1 + Phase 2 + cadence), see `../cargo-context/references/examples/lifecycle.md`.

References: ../cargo-context/SKILL.md

---

cargo-hosting

Cargo Hosting. Scaffold, deploy, and manage hosted apps (Vite SPAs on https://<slug>.cargo.app, built on @cargo-ai/app-sdk) and workers (serverless edge fetch(request, env) handlers on @cargo-ai/worker-sdk), plus the deployments that ship and promote them.

Lifecycle: init (local scaffold) → create (slot + globally-unique slug) → deployment create (build+upload) → deployment promote (go live).

Critical rules:

• --slug is the live subdomain — globally unique within the hosting domain.
• Deploying ≠ going live. deployment create builds; the URL only moves on deployment promote. deployment get-promoted shows what's live.
• --source is the package root, not dist/ — the build (npm ci && vite build for apps, bundling for workers) runs server-side.
• Builds are async — poll deployment get until terminal before promoting.
• --app-uuid / --worker-uuid are mutually exclusive on deployment commands; remove cascades to deployments.
• Folders come from `cargo-workspace-management`; --folder-uuid null moves to root.

References: ../cargo-hosting/SKILL.md

---

cargo-workspace-management

Workspace administration. 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.

Critical rules:

• Most commands require a token with admin access.
• workspaceManagement 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 `workspaceManagement 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:

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

See `references/uuid-flow.md` — producer/consumer table for every UUID and slug that crosses skill boundaries (workflowUuid, modelUuid, connectorUuid, actionSlug, …), the standard discovery sequence to run before any workflow, and the app.getcargo.io URL patterns for resolving UUIDs in the UI.

---

End-to-end use cases

See `references/use-cases.md` — 8 worked recipes (single-record enrich, batch + CRM sync, AI lead scoring, custom workflow from scratch, error monitoring, fresh-workspace bootstrap, segment export with filter+sort, GTM context audit) showing which skills to load and the command sequence for each.

---

Common gotchas

See `references/gotchas.md` — silent-failure footguns and frequently confused command pairs (conjonction spelling, run create vs batch create, --model-uuid vs --segment-uuid, storage query table naming, token-shown-once, invoice cents, third-party connector rate limits, context runtime execute vs write/edit, …).

Glossary

Key terms used across the Cargo CLI skills.

---

A

action A discrete operation that an AI agent or workflow can perform. Actions come in four kinds: tool (orchestration tool), connector (third-party integration action), agent (AI agent), and native (built-in platform action). Actions replace the previous "tools" terminology in AI releases and messages. Execute a single action with orchestration action execute, or a single action across multiple records with orchestration action execute-batch. To chain multiple actions, use run create with --nodes or batch create.

actionSlug A string identifier for a specific action on a workflow node. Present on both kind: "native" and kind: "connector" nodes.

• Native nodes — built-in Cargo actions discovered via cargo-ai connection native-integration get (keys of the actions object): start, end, branch, filter, variables, agent, python, script, etc. These are generic platform actions, not third-party service actions.
• Connector nodes — third-party service-specific actions discovered via cargo-ai connection integration get <slug> (e.g. integration get hubspot). Examples: company_enrich, create_contact, send_message. Do not use `native-integration get` for these — it will not return HubSpot, Salesforce, or other connector-specific actions.

agent An AI resource with configured instructions, a language model, and optional actions. Created and configured via cargo-ai. Used in workflows as a kind: "agent" node, or messaged directly via cargo-orchestration.

app (Cargo Hosting) A hosted Vite single-page app served on https://<slug>.cargo.app, built on @cargo-ai/app-sdk (Vite + refine, with getCargoEnv() / useCargoApi() wired to the workspace). Scaffolded with hosting app init, registered as a slot with hosting app create (which sets the globally-unique --slug), shipped via a deployment. Managed in the `cargo-hosting` skill. Distinct from a worker (a UI-less edge HTTP handler).

appUuid The UUID of a Cargo Hosting app, returned by hosting app create. Passed as --app-uuid to deployment commands (deployment create|list|get-promoted), mutually exclusive with --worker-uuid.

autocomplete A mechanism to fetch the list of allowed values for an action config field at runtime. When an action's uiSchema marks a field with "ui:widget": "IntegrationAutocompleteWidget", its valid values must be retrieved via cargo-ai connection connector autocomplete --connector-uuid <uuid> --slug <slug> --params '<json>'. The autocomplete slug and params come from the field's ui:options in the uiSchema. Returns { "results": [{ "label": "...", "value": "..." }] } — use the value in node configs.

---

B

batch A bulk execution of a workflow across multiple records. Created with orchestration batch create. Returns a batchUuid which is polled until status reaches success, error, or cancelled. Batches can be scoped to a segment, a list of record IDs, a file, or a filter.

batchUuid The UUID returned by batch create. Used to poll batch status (batch get), download results (batch download), and filter run metrics.

---

C

capability skill A skill that documents one CLI domain (orchestration, storage, connection, AI, content, context, analytics, billing, hosting, workspace management). Capability skills are the "standard library" — the agent loads them when it needs the syntax for a specific CLI command. They sit at the repo root alongside the outcome skill (cargo-gtm). Capability skills never reference outcome skills (one-way dependency: outcome → capability).

chat A conversation session between a user and an agent. Created with ai chat create --agent-uuid <uuid>. Messages are sent to a chat via ai message create --chat-uuid <uuid>.

conjonction The intentional French spelling used as the key name in Cargo filter JSON objects. Always "conjonction", never "conjunction". A typo here silently returns no records — no error is thrown.

column A typed field on a Cargo model. Each column has a slug, type (see column type below), label, and kind (see column kind below). Columns have no uuid — they are identified by slug within the model. Managed via cargo-storage (storage column list|create|update|remove|reorder). Column slug values are used in filter conditions and in storage query execute SQL queries.

column type The data type of a model column. Stored as the type field on the column object. Set on column create --type <value> and returned as type in column list and model list responses.

When building a filter condition, the condition's kind field must match the target column's type. A mismatch silently returns no records.

See cargo-orchestration/references/filter-syntax.md for the full filter reference with examples for each kind.

column kind How a column is sourced. Stored as the kind field on the column object. Determines whether the column is raw data or derived.

type and kind are independent: a computed column can have type: "string", a metric column has type: "number", etc.

connector An authenticated instance of an integration. For example, a specific HubSpot account connected to your workspace. Referenced by connectorUuid in workflow node graphs. Listed via connection connector list.

connectorUuid The UUID of a specific authenticated connector. Required for kind: "connector" nodes in workflow graphs and for filtering billing metrics.

context The workspace's git-backed knowledge base of typed markdown/MDX files capturing GTM truth: company narrative, ICPs, personas, JTBDs, plays, proof, objections, signals, mediums, alternatives, clients, insights. Read and written by both humans and agents. Managed via cargo-context (cargo-ai context runtime ... and cargo-ai context graph ...). Distinct from the system of record (Cargo storage queried with SQL) and from agent memories (per-agent mem0 entries).

content domain The CLI domain (cargo-ai content …) for workspace files and libraries — the binary/grouped knowledge attached to agents for RAG. Files and libraries moved here from the ai domain in CLI ≥ 1.0.19 (the old cargo-ai ai file … commands no longer exist). Documented in the `cargo-content` skill; attaching them to an agent lives in cargo-ai. Distinct from context (git-backed markdown).

context repository The GitHub repository that backs the workspace's context. Files in this repo follow strict conventions: kebab-case.md filenames, YAML frontmatter with required title and description, and domain/slug cross-refs without .md. The canonical example is `getcargohq/cargo-workspaces`. See cargo-context/references/conventions.md for the full domain list and per-domain templates.

credit The unit of consumption on Cargo. Workflows consume credits when they execute nodes — particularly connector and agent nodes. Tracked via cargo-billing.

---

D

dataset A logical grouping of models in the Cargo workspace. Similar to a schema or folder. Models belong to datasets. Listed via storage dataset list.

DDL Data Definition Language. In Cargo context, the result of storage model get-ddl <uuid> — contains the SQL table name, column definitions, and SQL dialect (language). Run when you need column types or the SQL dialect; storage query execute and storage query download reference tables by <datasetSlug>.<modelSlug> directly.

deployment (Cargo Hosting) One build+upload of a local source directory to a hosting app or worker, created with hosting deployment create --source <pkg-root> (the backend runs npm ci && vite build for apps, or bundles the entrypoint for workers). A deployment is not live until promoted — hosting deployment promote points the subdomain at it, and hosting deployment get-promoted shows what's currently live. Managed in the `cargo-hosting` skill.

deploymentUuid The UUID returned by hosting deployment create. Poll it with hosting deployment get <uuid> until the build status is terminal, then pass it to hosting deployment promote --uuid.

---

E

enrollment filter A segment filter condition (kind: "enrollment") that includes or excludes records based on their history with a workflow — whether they've entered it, how many times, or when they last left.

expression A dynamic config value in a node graph. Either a templateExpression using {{nodes.<slug>.<field>}} syntax, or a jsExpression using raw JavaScript. Used to pass data between nodes at runtime.

---

F

filter A JSON object used to select records from a model or segment. Always has the structure {"conjonction": "and"|"or", "groups": [...]}. See cargo-orchestration/references/filter-syntax.md for the full reference.

folder An organizational container for plays, tools, and agents in the Cargo app. Managed via cargo-workspace-management. Has no effect on workflow execution.

---

G

GTM (go-to-market) The set of activities for finding, qualifying, and engaging prospects: sourcing, enrichment, verification, scoring, sequencing, CRM sync, signal monitoring. The cargo-gtm outcome skill is cargo's front door for any GTM task.

---

H

hosting The CLI domain (cargo-ai hosting …) for Cargo Hosting — apps (Vite SPAs on *.cargo.app), workers (serverless edge HTTP handlers), and the deployments that ship and promote them. The lifecycle is init (local scaffold) → create (slot + globally-unique slug) → deployment create (build+upload) → deployment promote (go live). Documented in the `cargo-hosting` skill.

---

I

ICP (Ideal Customer Profile) The target prospect description used to filter sourcing and qualification: industry, size band, geography, tech stack, role, funding stage, etc. Every prospecting recipe begins by translating the user's stated ICP into provider filters. Often captured as a icp/<slug>.md file in the context repo.

ICP fit The degree to which a record matches the ICP. Often expressed as a 0–10 score from a scoring agent (anthropic.instruct or similar) over enriched record fields. See cargo-gtm/guides/writing-outreach.md for scoring patterns.

intent signal An observable behavior suggesting a company is ready to buy: hiring for a relevant role, raising funding, adding/removing tech in their stack, posting recent LinkedIn updates, anonymous website visits, recent job changes among employees. Cargo surfaces intent signals via cargo.enrichBusinessFunding…, theirStack.searchJobs, waterfall.detectJobChange, snitcher.searchSessions, and others. Tracked as signal/<slug>.md files in the context repo.

integration The external service type — e.g. HubSpot, Clearbit, Salesforce. Defines what actions are available. A single integration can have multiple connectors (multiple authenticated accounts). Listed via connection integration list.

integrationSlug The string identifier for an integration type (e.g. hubspot, clearbit, salesforce). Used in kind: "connector" node definitions alongside actionSlug.

---

K

knowledge graph The typed graph of nodes and cross-references derived from every markdown/MDX file in the context repository. Built (or loaded from cache) via cargo-ai context graph get. Each node carries parsed frontmatter (title, description) and outbound domain/slug references. Used to audit cross-references, discover existing entries, and power downstream agents that need the typed structure of the workspace's context. See cargo-context/references/examples/graph-queries.md for ready-to-run queries.

---

L

languageModelSlug The identifier for an LLM used by an agent or inline agent node. Examples: gpt-4o, gpt-4o-mini, claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022. Set on agent create or agent update.

library A collection in the content domain (cargo-ai content library …) that groups files into one resource an agent can reference for RAG. native libraries are workspace-managed; connector-backed libraries sync documents from an external source through an unstructured-data extractor (--extractor-slug).

---

M

MCP server A Model Context Protocol server that exposes additional actions to agents. Connected via cargo-ai. Once connected, agents can call MCP actions automatically during conversations or workflow runs.

memory A piece of information an agent stores from a conversation for future reference. Listed via ai memory list --agent-uuid <uuid>. Can be cleared with ai memory remove. Distinct from the context repository (workspace-wide, structured, git-backed) and from agent files / RAG resources.

model A structured data table in the Cargo workspace — e.g. Companies, Contacts, Deals. Has columns, relationships, and an associated SQL table in the system of record. Not to be confused with a language model.

modelUuid The UUID of a Cargo data model (table). Required for segment fetch, segment download, and as input to model get-ddl. Note: storage query execute references models by their slug (<datasetSlug>.<modelSlug>), not their UUID.

---

N

native integration A built-in Cargo integration type (distinct from third-party connector integrations). Native nodes (kind: "native") include built-in workflow actions like start, end, branch, filter, variables, agent, python, script. They have no rate limits.

node A single step in a workflow graph. Has a kind (native, connector, tool, or agent), a slug, a config, and childrenUuids pointing to downstream nodes.

node graph A directed acyclic graph (DAG) of nodes defining a workflow's execution steps. Passed as a JSON array to run create --nodes or batch create --nodes to override a workflow's deployed release.

---

O

outcome skill A skill the agent loads when the user states a real-world goal (e.g. "build a TAM list", "find 5 fintech CTOs", "monitor job changes"). The repo ships one outcome skill, `cargo-gtm`, which routes across all GTM scenarios via internal recipes (cargo-gtm/recipes/*.md). It composes actions across multiple CLI domains and delegates to capability skills via relative paths (../<name>/...). The "application library" sitting on top of the capability "standard library".

output node The terminal node of a workflow / tool / play whose output is the canonical result of a run. Identified by its slug (typically output or end) on the deployed release. Required input to cargo-ai orchestration run download-outputs --output-node-slug <slug> for retrieving action results.

---

P

play A segment-driven workflow that reacts automatically to data changes (records added, updated, or removed from a segment). Listed via orchestration play list. Triggered via batch create (not run create). The strategy behind a play is often captured as play/<slug>.md in the context repo (hypothesis, trigger, audience, channel, sequence, proof).

polling The pattern of repeatedly calling run get, batch get, or message get until the operation reaches a terminal state. See cargo-orchestration/references/polling.md for intervals and shell snippets.

persona A role / title shape that's part of the ICP. Example personas: "Head of RevOps at a B2B SaaS", "Founder at a seed-stage fintech". Used as filters for salesNavigator.searchLeads, peopleDataLabs.searchPeople, etc. Captured as persona/<slug>.md in the context repo with role, KPIs, pains, motivations, preferred channels, and common objections.

priority stack The 6 default credits-based providers used as the spine of every recipe in cargo-gtm/: salesNavigator (sourcing), cargo native (firmographic + signal intelligence), waterfall (multi-source enrichment + verification + job-change signal), FullEnrich (premium contact lookup), theirStack (tech-stack + hiring intent), peopleDataLabs (heavyweight backfill). See cargo-gtm/SKILL.md for the full stack reference and per-provider playbooks.

proof An atomic proof point — one metric, quote, case fact, or benchmark — stored as proof/<slug>.md in the context repo. Cross-referenced from plays, objections, and decks. Keep proof entries atomic (one fact per file) so they can be filtered in the knowledge graph.

prospect A person being marketed or sold to — typically resolved to a prospect_id via cargo.matchProspect. Distinct from a "lead" (which usually implies an inbound or marketing-qualified context); cargo uses "prospect" generically.

prospecting The activity of finding prospects matching an ICP, enriching them with contact details and signals, and preparing them for outreach. Cargo's prospecting recipe lives at cargo-gtm/recipes/prospecting.md.

---

R

RAG (Retrieval-Augmented Generation) A pattern where an agent references uploaded files (PDFs, CSVs, text) or libraries to ground its responses in specific knowledge. Files are uploaded via cargo-ai content file upload (libraries via content library) and attached to agents through the release's resources.

record A single row in a Cargo model (e.g. one company, one contact). Identified by a recordId. Processed individually by runs or in bulk by batches.

recordId The identifier of a specific record in a model. Used in batch create --data '{"kind":"recordIds","recordIds":["id1","id2"]}' to target specific records for processing.

release A snapshot of a workflow's node graph at a point in time. When a workflow is deployed, a release is created. Runs and batches execute against a specific release. Referenced by releaseUuid.

releaseUuid The UUID of a specific workflow release. Returned by batch get → .releaseUuid. Used to fetch node slugs via release get (needed for batch download --output-node-slug).

run A single execution of a tool workflow against one record. Created with orchestration run create. Returns a runUuid polled until status reaches success, error, or cancelled.

runUuid The UUID of a single workflow run. Used to poll status (run get), inspect results, and filter analytics.

runtime sandbox A checked-out, executable copy of the context repository that backs every cargo-ai context runtime ... command. runtime write and runtime edit commit and push to the default branch; runtime execute runs a shell command in the sandbox but does not push any file changes. Use execute for inspection (grep, ls, find); use write/edit for any change that should land in git.

---

S

segment A filtered, live view of records in a model. Defined by a filter condition. Used as the trigger population for plays and as a data source for batch runs. Listed via segmentation segment list.

segmentUuid The UUID of a segment. Used in batch create --data '{"kind":"segment","segmentUuid":"..."}'. Note: segment fetch and segment download require --model-uuid, not --segment-uuid.

slug A human-readable string identifier used throughout the platform. Node slugs identify nodes within a graph (e.g. enrich_company). Integration slugs identify integration types (e.g. clearbit). Column slugs identify model columns. Slugs use only [a-zA-Z0-9_]. In the context repository, slugs are kebab-case filenames without the .md extension and are referenced as domain/slug.

signal See intent signal. In cargo recipes, signals are the basis for segment construction (e.g. "all companies that just raised funding AND are hiring engineers") and outbound timing. Captured as signal/<slug>.md files in the context repo.

sourcing The activity of finding companies or people matching ICP criteria. Cheapest at-scale options: salesNavigator.searchLeads (0.02 cred/record), salesNavigator.searchAccounts (0.05). For investor / funding / complex filters: peopleDataLabs.queryCompanies (3). For local SMBs: serper.searchPlaces (1).

system of record (SoR) Cargo's storage layer, backed by a customer-connected database (BigQuery, Snowflake, etc.) that Cargo queries via SQL. Queried with cargo-ai storage query execute "<sql>" (or storage query download --query "<sql>" for full exports), which references tables as <datasetSlug>.<modelSlug> (e.g. default.companies). Use cargo-ai storage model get-ddl <model-uuid> for column types and SQL dialect. Distinct from the context repository (markdown/MDX knowledge base, not relational data) and from the orchestration query surface (cargo-ai orchestration query execute, which targets the runs/batches/spans/records runtime tables).

---

T

TAM (Total Addressable Market) The full universe of companies (and optionally contacts at those companies) matching an ICP. Cargo's TAM-build recipe lives at cargo-gtm/recipes/build-tam.md, typically producing 100–10,000 company lists.

template A pre-built blueprint for a workflow node graph (orchestration template list) or an AI agent (ai template list). Used to bootstrap common patterns without building from scratch. In the context repository, every domain also ships a _template.md documenting the expected sections (read it with cargo-ai context runtime read --path <domain>/_template.md).

temperature A float between 0.0 and 1.0 controlling how deterministic an agent's responses are. 0.0 = fully deterministic; 1.0 = highly creative. Set on agent create or agent update.

tool An on-demand workflow triggered manually, via API, or on a cron schedule. Listed via orchestration tool list. Supports both run create (single record) and batch create (multiple records).

---

U

uiSchema A companion object to jsonSchema in action and extractor configs. While jsonSchema defines the types and structure of fields, uiSchema provides UI rendering hints. The most important hint for CLI usage is "ui:widget": "IntegrationAutocompleteWidget" — this signals that the field's allowed values must be fetched dynamically using connector autocomplete rather than set to a freeform value. The ui:options.slug identifies which autocomplete endpoint to call, and ui:options.params (if present) specifies dependencies on other fields. See cargo-connection for the full autocomplete workflow.

---

W

waterfall enrichment A pattern where multiple providers are run sequentially, each filling gaps the prior step missed. Cheap providers do the heavy lifting; premium providers fill the long tail. Implemented as N sequential action execute-batch calls with the records pruned between calls. See cargo-gtm/references/waterfall-strategy.md for canonical chains by enrichment goal.

worker (Cargo Hosting) A hosted serverless HTTP handler that runs on the edge — a standard fetch(request, env) entrypoint built on @cargo-ai/worker-sdk (automatic OpenAPI 3.1 spec at /openapi.json, Swagger UI at /docs). Scaffolded with hosting worker init, registered with hosting worker create, shipped via a deployment. Has no env subcommand (unlike an app) — runtime config arrives via the env argument to fetch. Managed in the `cargo-hosting` skill.

workerUuid The UUID of a Cargo Hosting worker, returned by hosting worker create. Passed as --worker-uuid to deployment commands, mutually exclusive with --app-uuid.

workflow A DAG of nodes that defines the execution logic for a play or tool. Workflows don't have a name field — find them by name via play list or tool list, then extract workflowUuid.

workflowUuid The UUID of a workflow. The primary key for most orchestration, analytics, and billing commands. Get it from play list or tool list → .workflowUuid.

workspace The top-level organizational unit in Cargo. All resources (models, agents, workflows, connectors, the context repository) belong to a workspace. Identified by a workspaceUuid. Managed via cargo-workspace-management.

Common gotchas

Silent-failure footguns and frequently confused command pairs across the Cargo CLI. Skim before designing a new workflow or debugging unexpected empty results.

Cargo CLI — prerequisites

The same install, login, and runtime conventions apply to every Cargo skill in this bundle. Each capability skill links here instead of duplicating the boilerplate. Load the `cargo` router skill first if you haven't already — it covers session refresh and skill routing.

Install

npm install -g @cargo-ai/cli

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

Authenticate

cargo-ai login --oauth                                  # browser sign-in (recommended)
# or: cargo-ai login --token <your-api-token>           # workspace-scoped API token (non-interactive)
# Pin a default workspace at login (with --oauth)
cargo-ai login --oauth --workspace-uuid <uuid>

--oauth runs the OAuth 2.0 Device Authorization Flow — no client setup. For CI / scripts, use --token with a workspace-scoped API token from Settings > API. Token values are shown only once; store immediately in a secrets manager.

Verify

cargo-ai whoami
# → { "user": { "uuid": ..., "email": ... }, "workspace": { "uuid": ..., "name": ... } }

Always confirm workspace.name before any write — there is no dry-run mode for destructive commands. If the active workspace is wrong, re-run cargo-ai login --oauth --workspace-uuid <uuid> (or --token <workspace-scoped-token> for non-interactive use).

Output conventions

• All commands output JSON to stdout.
• Successful commands exit 0.
• Failed commands exit non-zero and return {"errorMessage": "..."} — read this field for the cause.
• Async commands (run create, batch create, message create, action execute, action execute-batch) return a UUID and a status that starts as pending / running. Pass --wait-until-finished to block, or poll the matching get command. See `cargo-orchestration/references/polling.md` for intervals and retry guidance.

Admin-only commands

Some domains require a token with admin access on the workspace:

• All of cargo-billing (usage metrics, subscription, invoices).
• Most of cargo-workspace-management (users, roles, tokens — folder and report writes work with non-admin tokens).

If a command returns {"errorMessage":"forbidden"} or unauthorized, the token likely lacks admin scope. Re-issue with an admin user, or ask a workspace admin to run the command.

When the CLI fails

Whenever a CLI command misbehaves, a documented flag is missing, or you've retried the same command twice without progress, file a workspace management report:

cargo-ai workspaceManagement report create \
  --title "<one-line summary>" \
  --description "<command(s) tried, errorMessage, expected vs actual, relevant UUIDs>"

This is the official feedback channel — every report is reviewed by the Cargo team. See `cargo-workspace-management/SKILL.md` (Reports section) for the full template.

End-to-end use cases

Worked recipes showing which skills to load and the command sequence for common Cargo scenarios. Use these as a starting point — each links to the relevant skill docs for the full per-command reference.

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. workspaceManagement token create --name <label>   → create a dedicated, named API token
2. workspaceManagement role list             → discover available roles
3. workspaceManagement 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. workspaceManagement 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"}]'

8. Author and audit the workspace's GTM context repo

Skills needed: cargo-context

1. context runtime browse                          → see the domain layout
2. context runtime read --path persona/_template.md → grab the template for the target domain
3. context runtime write --path persona/<slug>.md  → add the entry (frontmatter + body, pushes to default branch)
4. context graph get | jq …                        → audit cross-refs, find plays missing proof, etc.

See ../../cargo-context/references/examples/authoring.md and ../../cargo-context/references/examples/graph-queries.md for full recipes.

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.

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 dataset slug) for SoR queries
cargo-ai storage model list
cargo-ai storage dataset list
cargo-ai storage model get-ddl <model-uuid>   # optional — for column types and SQL dialect

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

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