getcargohq__cargo-skills/cargo/references/use-cases.md

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"}'
   --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

Credentials in step 1: the token create response is the only time the token value is shown — hand it to the user for a secrets manager (GitHub Secrets, AWS Secrets Manager) rather than echoing it into a file, a commit, or the transcript. Scope it to what the job needs: most of this bootstrap requires admin, but the token that later runs plays or batches does not. Steps 1 and 3 change who can see and touch workspace data, so confirm the token's scope and the invite list with the user before running them.

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.