cargo
Original:🇺🇸 English
Translated
Router and overview for the Cargo CLI agent skills. Explains the eleven skills (one outcome skill cargo-gtm + ten capability skills), the UUID flow between them, async polling, end-to-end use cases (enrich one record, enrich and sync to CRM, AI lead scoring, custom workflow, error monitoring, fresh-workspace bootstrap, segment export, GTM context authoring), and common gotchas (`conjonction` spelling, run vs batch, model-uuid vs segment-uuid). Load first whenever working with the Cargo CLI, when unsure which sub-skill applies, when stitching multiple sub-skills together, when bootstrapping a workspace, or when the user asks about Cargo skills in general.
13installs
Sourcegetcargohq/cargo-skills
Added on
NPX Install
npx skill4agent add getcargohq/cargo-skills cargoTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →██████ ████ █████ ██████ ██████
██ ░ ██ ██░ ██ ██ ██ ░ ██ ██░
██ ██████░ █████ ░ ██ ███ ██ ██░
██ ██ ██░ ██ ██ ██ ██░ ██ ██░
██████ ██ ██░ ██ ██ ██████░ ██████░
░░░░░░ ░░ ░░ ░░ ░░ ░░░░░░ ░░░░░░Cargo CLI — Skills Overview
This repository contains 11 skills at the repo root: one outcome skill () 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) and provider playbooks (../cargo-gtm/recipes/*.md).../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 , or directly when you need a specific CLI domain.
cargo-gtm
cargo-gtmcargo-gtmGlossary: See for term-by-term definitions (UUIDs, slugs, , run/batch/play/tool, signal/persona/ICP, etc.).
references/glossary.mdconjonctionInstallation
bash
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 whoamiWithout a global install, prefix every command with instead of .
npx @cargo-ai/clicargo-aiAll commands output JSON to stdout. Failed commands exit non-zero and return . For the full setup conventions that every capability skill links to (token scopes, async polling, admin-only commands), see .
{"errorMessage": "..."}references/prerequisites.mdEvery Cargo session has three jobs
Automated by the Cargo installer. Jobs 1 and 3 (refresh + session register/finalize) run on their own when the/SessionStarthooks scaffolded bySessionEndare present. Do them by hand only when those hooks aren't installed. Job 2 (reporting) is always your responsibility — it can't be automated.curl -fsSL https://api.getcargo.io/install.sh | sh
1. At session start — refresh and register
Before any other Cargo command, refresh the CLI and skills, then register the session in workspace management:
bash
# 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 only if the user opted out or no is available.
session upsertsession_id2. 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 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:
--helpbash
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 (Reports section) and for templates.
../cargo-workspace-management/SKILL.md../cargo-workspace-management/references/examples/reports.md3. 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_atbash
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--summary--finishedfinished_at = now--finished-at <iso>Skills at a glance
Outcome skill
Load when the user states a real-world goal.
| Skill | Load when you need to… |
|---|---|
| Any GTM task — sourcing, enrichment, verification, scoring, sequencing, CRM sync, signal monitoring (job changes, funding, tech-stack/hiring intent). Routes via recipes ( |
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.
| Skill | Load when you need to… |
|---|---|
| Execute actions, run workflows, trigger batches, chat with agents, query orchestration with SQL (ClickHouse) |
| Download run results, export segment data, monitor error rates and metrics |
| Check credit usage, view subscription details, track costs per workflow or connector |
| Inspect or modify data models, columns, datasets, and relationships; query workspace storage with SQL |
| Manage connector authentication, discover available integrations and their actions |
| Create and configure agents, configure releases, attach knowledge for RAG, manage MCP servers and memories |
| Upload and organize knowledge files, build native/connector-backed knowledge libraries for RAG (the |
| Browse/read/write/edit the workspace's git-backed GTM context repo, run commands in its runtime sandbox, inspect the knowledge graph |
| Scaffold, deploy, and promote hosted apps (Vite SPAs on |
| Invite users, create API tokens, organize folders, manage roles, report CLI issues to management |
Agent knowledge for RAG: files + libraries live in thedomain →content; how they attach to an agent →cargo-content. (Files/libraries moved out of the oldcargo-aipath in CLI ≥ 1.0.19.)ai file …
CLI domains without a dedicated skill yet
The CLI exposes several domains that no capability skill wraps yet. Reach for them directly () when a task needs them, and file a if the surface is unclear:
cargo-ai <domain> --helpworkspaceManagement report| CLI domain | Covers |
|---|---|
| Segments and changes ( |
| Recipes and expression evaluation ( |
| System-of-record, client, and log operations. |
| Allocations, capacities, members, territories (revenue/territory planning). |
| Current-user operations with no workspace context. |
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:
- delegates to capability skills via relative paths (
cargo-gtm). Capability skills never reference../cargo-orchestration/....cargo-gtm - provides auth context for every skill — set it up first.
cargo-workspace-management - ,
cargo-storage, andcargo-connectionare peer skills that supply UUIDs tocargo-ai. They don't depend on each other.cargo-orchestration - owns workspace files and libraries (the
cargo-contentdomain). It produces file/library UUIDs thatcontentconsumes as agent releasecargo-ai(RAG). Uploaded content files also surface read-only underresourcesin the.files/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.
cargo-context - For SQL queries against storage, use (tables as
cargo-ai storage query execute "<sql>"). Load<datasetSlug>.<modelSlug>to discover dataset and model slugs, and to fetch the DDL when you need column types or the SQL dialect.cargo-storage - For SQL queries against orchestration runtime tables (,
runs,batches,spans) — error rates, per-node failures, time-series — userecords. Workspace scoping is automatic; tables are referenced without a schema prefix.cargo-ai orchestration query execute "<sql>" - Before building a workflow node graph, load to get
cargo-connectionandconnectorUuid.actionSlug - Before executing a workflow that uses an agent node, load to get
cargo-ai.agentUuid - After runs complete, load to download results or measure performance. For action output retrieval, prefer
cargo-analyticsovercargo-ai orchestration run download-outputs— the former returns a signed-URL CSV/JSON of just the output node's data.run download - Load to understand credit consumption for any of the above.
cargo-billing
Skill details
cargo-gtm
The outcome skill — front door for any GTM task. Bundles routing (), phase guides (), scenario recipes (), per-provider playbooks (), references (), and a sub-agent ().
SKILL.mdguides/recipes/provider-playbooks/references/agents/Recipes shipped:
| Recipe | Use when… |
|---|---|
| End-to-end find → enrich → verify → sync (P1/P2/P3 variants). |
| Build a Total Addressable Market list at scale (100–10,000 companies). |
| Resolve LinkedIn URL from name + company with strict validation. |
| Investor / accelerator → portfolio companies → contacts. |
| |
| Track companies that recently raised funding. |
| Find companies by tech-stack or hiring-intent signals. |
| Diff Closed-Won vs Closed-Lost segments, surface ICP signals. |
| Turn a signal segment into send-ready outreach (enrich → verify → personalize → sequencer handoff). |
| Wake up stale contacts only when a fresh signal fires (job change, funding, tech intent). |
| Revive Closed-Lost CRM deals by branching on |
| Multi-thread customer accounts — net-new buyers, deduped against the Contacts model. |
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 (→ 141 credits-based actions across 120 integrations).
cargo-ai connection integration list - Action shape: — no
{"kind":"connector","integrationSlug":"<slug>","actionSlug":"<slug>","config":{}}inconnectorUuid.config - Output retrieval: (NOT
cargo-ai orchestration run download-outputs --output-node-slug <slug>).run download - peopleDataLabs filter shape: uses cargo's
searchXshape;{conjonction, groups, conditions}takes a PDL SQL string — never Elasticsearch.queryX
References:
../cargo-gtm/SKILL.mdcargo-orchestration
The execution hub. Execute actions, run workflows, chat with AI agents, query orchestration runtime tables (///) with SQL, and fetch segment records.
runsbatchesspansrecordsCritical rules:
- See the decision flowchart at the top of for when to use
../cargo-orchestration/SKILL.mdvsaction executevsrun create.batch create - Prefer built-in actions + expressions when building a node graph. Avoid ,
python(JS), and raw HTTP nodes unless necessary: usescriptfor transforms, the nativevariablesnode for LLM calls, the integration's dedicated connector action for APIs, andagent/branch/filterfor routing. Seeswitch.../cargo-orchestration/references/node-selection.md - Filter JSON uses (not
conjonction) — breaks silently if misspelled.conjunction - Query orchestration runtime tables (ClickHouse) with against
cargo-ai orchestration query execute "<sql>",runs,batches,spans(no schema prefix; workspace scoping is automatic).records - For SQL against workspace storage (Companies, Contacts, …), use — documented in
cargo-ai storage query execute "<sql>".cargo-storage - All operations are async — poll or pass . See Async polling.
--wait-until-finished
References:
../cargo-orchestration/SKILL.mdcargo-analytics
Measurement and export. Download run results, export segment data, and monitor error rates and success metrics.
Critical rules:
- requires
segment download, not--model-uuid.--segment-uuid - For batch result download, get the from
output-node-slug→release get <release-uuid>.nodes[].slug - For billing and credit usage, use instead.
cargo-billing
References:
../cargo-analytics/SKILL.mdcargo-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.
- from
subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount= remaining credits.subscription get
References:
../cargo-billing/SKILL.mdcargo-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 (or
cargo-ai storage query execute "<sql>"for full exports) usingstorage query download --query "<sql>"table names (e.g.<datasetSlug>.<modelSlug>).default.companiesis optional — useful for column types and SQL dialect.model get-ddl - For SQL against orchestration runtime tables (/
runs/batches/spans), userecords— documented incargo-ai orchestration query execute "<sql>".cargo-orchestration - For advanced record queries (filtering, sorting, pagination), use from
segmentation segment fetch.cargo-orchestration
References:
../cargo-storage/SKILL.mdcargo-connection
Connector and integration management. Authenticate external services, discover supported actions, get the and values needed for workflow node graphs.
connectorUuidactionSlugKey concepts:
- Integration = external service type (HubSpot, Clearbit, Salesforce, …)
- Connector = authenticated instance of an integration (referenced by in nodes)
connectorUuid
References:
../cargo-connection/SKILL.mdcargo-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 : files + libraries come from
resources. Wire them in withcargo-contentthenrelease update-draft --resources ….release deploy-draft - CLI ≥ 1.0.19: files and libraries moved out of the domain into the top-level
aidomain (now thecontentskill). The oldcargo-contentcommands no longer exist.cargo-ai ai file …
For using agents (sending messages, multi-turn chat, polling), use.cargo-orchestration
See for model and temperature guidance by use case.
../cargo-ai/SKILL.mdReferences:
../cargo-ai/SKILL.mdcargo-content
Workspace knowledge files & libraries. Upload, list, rename, move, and remove files (PDFs, CSVs, text); create and sync libraries — (workspace-managed) or -backed (synced from an external source via an unstructured-data extractor). These are the RAG knowledge resources agents reference.
nativeconnectorCritical rules:
- New top-level domain in CLI ≥ 1.0.19 —
content/cargo-ai content file …. The oldcargo-ai content library …path is gone (cargo-ai ai file …→ you're on the old path; bump the CLI).unknown command - A file or library is inert until attached to an agent's deployed release — that wiring lives in
resources.cargo-ai - Uploaded content files are also readable (read-only) under in the
.files/runtime sandbox.cargo-context - For batch-run input files (CSVs that drive a batch), use (a different surface) — see
cargo-ai workspaceManagement file upload.cargo-workspace-management
References:
../cargo-content/SKILL.mdcargo-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: . Files use
getcargohq/cargo-workspacesnames, YAML frontmatter with requiredkebab-case.md+title, anddescriptioncross-refs (nodomain/slug)..md - Runtime sandbox = a checked-out, executable copy of the context repo. and
runtime writepush to the default branch;runtime editdoes not push.runtime execute - 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 writecommit and push.runtime editis ephemeral — use it forruntime execute/grep/inspection, never for persistent changes.ls - must match the file content exactly once. Read first, copy whitespace verbatim.
runtime edit --old-string - Set +
titlefrontmatter on everydescription/.mdfile — a strong convention, not enforced: missing/malformed frontmatter is still committed, it just indexes poorly (graph falls back to filename + first paragraph, and reads.mdx, notsummary).description - Graph edges form only from frontmatter , markdown links, or wikilinks — a bare path in prose creates no edge. Cite source files in
references:.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.mdcargo-hosting
Cargo Hosting. Scaffold, deploy, and manage hosted apps (Vite SPAs on , built on ) and workers (serverless edge handlers on ), plus the deployments that ship and promote them.
https://<slug>.cargo.app@cargo-ai/app-sdkfetch(request, env)@cargo-ai/worker-sdkLifecycle: (local scaffold) → (slot + globally-unique slug) → (build+upload) → (go live).
initcreatedeployment createdeployment promoteCritical rules:
- is the live subdomain — globally unique within the hosting domain.
--slug - Deploying ≠ going live. builds; the URL only moves on
deployment create.deployment promoteshows what's live.deployment get-promoted - is the package root, not
--source— the build (dist/for apps, bundling for workers) runs server-side.npm ci && vite build - Builds are async — poll until terminal before promoting.
deployment get - /
--app-uuidare mutually exclusive on deployment commands;--worker-uuidcascades to deployments.remove - Folders come from ;
cargo-workspace-managementmoves to root.--folder-uuid null
References:
../cargo-hosting/SKILL.mdcargo-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.
- requires
workspaceManagement token create(the legacy--nameflag was removed). Pick a name that makes the token's purpose obvious in--from-userlater.token list - Token values are only shown once at creation — store immediately in a secrets manager (GitHub Secrets, AWS Secrets Manager, etc.).
- Always send a 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
workspaceManagement report create.../cargo-workspace-management/references/examples/reports.md
References:
../cargo-workspace-management/SKILL.mdAsync polling
All operations are asynchronous. Pass to block, or poll:
--wait-until-finished| Result type | Poll command | Interval | Terminal when |
|---|---|---|---|
| Run | | 2s | |
| Batch | | 5s | |
| Agent message | | 2s | |
action executeaction execute-batchSee for retry strategies, error handling, and large-batch guidance.
../cargo-orchestration/references/polling.mdUUID flow between skills
See — producer/consumer table for every UUID and slug that crosses skill boundaries (, , , , …), the standard discovery sequence to run before any workflow, and the URL patterns for resolving UUIDs in the UI.
references/uuid-flow.mdworkflowUuidmodelUuidconnectorUuidactionSlugapp.getcargo.ioEnd-to-end use cases
See — 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.
references/use-cases.mdCommon gotchas
See — silent-failure footguns and frequently confused command pairs ( spelling, vs , vs , storage query table naming, token-shown-once, invoice cents, third-party connector rate limits, vs /, …).
references/gotchas.mdconjonctionrun createbatch create--model-uuid--segment-uuidcontext runtime executewriteedit