██████ ████ █████ ██████ ██████
██ ░ ██ ██░ ██ ██ ██ ░ ██ ██░
██ ██████░ █████ ░ ██ ███ ██ ██░
██ ██ ██░ ██ ██ ██ ██░ ██ ██░
██████ ██ ██░ ██ ██ ██████░ ██████░
░░░░░░ ░░ ░░ ░░ ░░ ░░░░░░ ░░░░░░
Cargo CLI — Skills Overview
This repository contains 11 skills at the repo root: one
outcome skill (
) and ten
capability skills.
- — 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 , or directly when you need a specific CLI domain.
delegates to capability skills; capability skills never reference
(one-way dependency).
Glossary: See
for term-by-term definitions (UUIDs, slugs,
, run/batch/play/tool, signal/persona/ICP, etc.).
Installation
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 whoami
Without a global install, prefix every command with
instead of
.
All 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
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
/
hooks scaffolded by
curl -fsSL https://api.getcargo.io/install.sh | sh
are present. Do them by hand only when those 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:
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.
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
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:
bash
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 .
- 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
:
bash
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
and
are required (NOT NULL).
stamps
; pass
for an explicit timestamp.
Skills at a glance
Outcome skill
Load when the user states a real-world goal.
| Skill | Load when you need to… |
|---|
| (recap) | Any GTM task — sourcing, enrichment, verification, scoring, sequencing, CRM sync, signal monitoring (job changes, funding, tech-stack/hiring intent). Routes via recipes (), guides (), and provider playbooks (). |
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… |
|---|
| (recap) | Execute actions, run workflows, trigger batches, chat with agents, query orchestration with SQL (ClickHouse) |
| (recap) | Download run results, export segment data, monitor error rates and metrics |
| (recap) | Check credit usage, view subscription details, track costs per workflow or connector |
| (recap) | Inspect or modify data models, columns, datasets, and relationships; query workspace storage with SQL |
| (recap) | Manage connector authentication, discover available integrations and their actions |
| (recap) | Create and configure agents, configure releases, attach knowledge for RAG, manage MCP servers and memories |
| (recap) | Upload and organize knowledge files, build native/connector-backed knowledge libraries for RAG (the domain) |
| (recap) | Browse/read/write/edit the workspace's git-backed GTM context repo, run commands in its runtime sandbox, inspect the knowledge graph |
| (recap) | Scaffold, deploy, and promote hosted apps (Vite SPAs on ) and edge workers (serverless HTTP handlers), and manage their deployments |
cargo-workspace-management
(recap) | Invite users, create API tokens, organize folders, manage roles, report CLI issues to management |
Agent knowledge for RAG: files +
libraries live in the
domain →
; how they attach to an agent →
. (Files/libraries moved out of the old
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 (
) when a task needs them, and file a
workspaceManagement report
if the surface is unclear:
| CLI domain | Covers |
|---|
| Segments and changes (segment list/get/create/fetch/download
, ). Some of this is already used from /. |
| Recipes and expression evaluation (, ) — generate/evaluate the template expressions used in node graphs. |
| 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-orchestration/...
). Capability skills never reference .
cargo-workspace-management
provides auth context for every skill — set it up first.
- , , and are peer skills that supply UUIDs to . They don't depend on each other.
- owns workspace files and libraries (the domain). It produces file/library UUIDs that consumes as agent release (RAG). Uploaded content files also surface read-only under in the runtime sandbox.
- 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 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 (, , , ) — 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 to get and .
- Before executing a workflow that uses an agent node, load to get .
- After runs complete, load to download results or measure performance. For action output retrieval, prefer
cargo-ai orchestration run download-outputs
over — the former returns a signed-URL CSV/JSON of just the output node's data.
- Load to understand credit consumption for any of the above.
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 (
).
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). |
recipes/linkedin-url-lookup.md
| Resolve LinkedIn URL from name + company with strict validation. |
recipes/portfolio-prospecting.md
| Investor / accelerator → portfolio companies → contacts. |
recipes/job-change-monitoring.md
| waterfall.detectJobChange
(cargo-unique) on a contact segment. |
| 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. |
recipes/outreach-activation.md
| 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). |
recipes/lost-deal-revival.md
| Revive Closed-Lost CRM deals by branching on (champion left, budget, timing). |
recipes/account-expansion.md
| 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 (
cargo-ai connection integration list
→ 141 credits-based actions across 120 integrations).
- Action shape:
{"kind":"connector","integrationSlug":"<slug>","actionSlug":"<slug>","config":{}}
— no in .
- Output retrieval:
cargo-ai orchestration run download-outputs --output-node-slug <slug>
(NOT ).
- peopleDataLabs filter shape: uses cargo's
{conjonction, groups, conditions}
shape; takes a PDL SQL string — never Elasticsearch.
cargo-orchestration
The execution hub. Execute actions, run workflows, chat with AI agents, query orchestration runtime tables (
/
/
/
) with SQL, and fetch segment records.
Critical rules:
- See the decision flowchart at the top of
../cargo-orchestration/SKILL.md
for when to use vs vs .
- Prefer built-in actions + expressions when building a node graph. Avoid , (JS), and raw HTTP nodes unless necessary: use for transforms, the native node for LLM calls, the integration's dedicated connector action for APIs, and // for routing. See
../cargo-orchestration/references/node-selection.md
.
- Filter JSON uses (not ) — breaks silently if misspelled.
- Query orchestration runtime tables (ClickHouse) with
cargo-ai orchestration query execute "<sql>"
against , , , (no schema prefix; workspace scoping is automatic).
- For SQL against workspace storage (Companies, Contacts, …), use
cargo-ai storage query execute "<sql>"
— documented in .
- All operations are async — poll or pass . 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:
- requires , not .
- For batch result download, get the from
release get <release-uuid>
→ .
- For billing and credit usage, use 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 = 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. ). is optional — useful for column types and SQL dialect.
- For SQL against orchestration runtime tables (///), use
cargo-ai orchestration query execute "<sql>"
— documented in .
- For advanced record queries (filtering, sorting, pagination), use
segmentation segment fetch
from .
References: ../cargo-storage/SKILL.md
cargo-connection
Connector and integration management. Authenticate external services, discover supported actions, get the
and
values needed for workflow node graphs.
Key concepts:
- Integration = external service type (HubSpot, Clearbit, Salesforce, …)
- Connector = authenticated instance of an integration (referenced by 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 : files + libraries come from . Wire them in with
release update-draft --resources …
then .
- CLI ≥ 1.0.19: files and libraries moved out of the domain into the top-level domain (now the skill). The old commands no longer exist.
For
using agents (sending messages, multi-turn chat, polling), use
.
See
for model and temperature guidance by use case.
cargo-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.
Critical rules:
- New top-level domain in CLI ≥ 1.0.19 — /
cargo-ai content library …
. The old path is gone ( → you're on the old path; bump the CLI).
- A file or library is inert until attached to an agent's deployed release — that wiring lives in .
- Uploaded content files are also readable (read-only) under in the 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 names, YAML frontmatter with required + , and cross-refs (no ).
- Runtime sandbox = a checked-out, executable copy of the context repo. and push to the default branch; 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:
- / commit and push. is ephemeral — use it for //inspection, never for persistent changes.
runtime edit --old-string
must match the file content exactly once. Read first, copy whitespace verbatim.
- Set + frontmatter on every / 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 , not ).
- Graph edges form only from frontmatter , markdown links, or wikilinks — a bare path in prose creates no edge. Cite source files in .
- 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
, built on
) and
workers (serverless edge
handlers on
), plus the
deployments that ship and promote them.
Lifecycle: (local scaffold) →
(slot + globally-unique slug) →
(build+upload) →
(go live).
Critical rules:
- is the live subdomain — globally unique within the hosting domain.
- Deploying ≠ going live. builds; the URL only moves on . shows what's live.
- is the package root, not — the build ( for apps, bundling for workers) runs server-side.
- Builds are async — poll until terminal before promoting.
- / are mutually exclusive on deployment commands; cascades to deployments.
- Folders come from
cargo-workspace-management
; 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 (the legacy flag was removed). Pick a name that makes the token's purpose obvious in 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
to block, or poll:
| Result type | Poll command | Interval | Terminal when |
|---|
| Run | cargo-ai orchestration run get <uuid>
| 2s | is , , or |
| Batch | cargo-ai orchestration batch get <uuid>
| 5s | is , , or |
| Agent message | cargo-ai ai message get <uuid>
| 2s | is or |
returns a run;
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
— 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.
End-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.
Common 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
/
, …).