Name: cargo
Author: getcargohq

Router for the Cargo CLI skill bundle — load first for anything Cargo, and whenever a task spans two Cargo domains. Explains what each skill owns, declarative workspace-as-code (cargo-cdk) vs the imperative CLI, the UUID and slug flow between skills, async polling of runs and batches, end-to-end use

Cargo CLI — Skills Overview This repository contains 19 skills at the repo root: this router ( cargo ), one onboarding skill ( cargo quickstart ), one outcome skill ( cargo gtm ), and sixteen capability skills . cargo quickstart — guided first run demo. Fresh workspace → real deliverable (25 leads for the user's persona, with a cost receipt) in under two minutes, ending by saving the demo as a recurring play. Load for new users, demo/tour requests, or empty workspaces. 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, segmentation, connection, AI, content, context, analytics, billing, observability, hosting, project, mailbox management, workspace management), plus cargo diagnostics (cross domain forensics over runs, batches, and credit spend) and cargo mcp (the hosted MCP server, the one surface that is not the CLI). Loaded by cargo gtm , or directly when you need a specific CLI domain. cargo project — the declarative one. Where the other capability skills wrap imperative one off cargo ai <domain calls, cargo project declares the whole workspace in a project — the folder holding cargo.json ( define builders + cargo ai project deploy ) — and reconciles it. It spans every resource type — see "Declarative vs imperative" below to route between it and the imperative skills. cargo gtm delegates to capability skills; capability skills never reference cargo gtm (one way dependency). Glossary: See [ references/glossary.md ](references/glossary.md) for term by term definitions (UUIDs, slugs, conjonction , run/batch/play/tool, signal/persona/ICP, etc.). Interaction conventions: See [ references/interaction.md ](references/interaction.md) for the pack wide defaults on when to stop and ask (plan gate before building, recommended default choices) and how to present results (narrate, summarize — never dump raw JSON). Installation Look before signing up. With no account at all, cargo ai orchestration action list <keywords , connection integration list get and orchestration action execute … dry run (connector and native actions: validates data , prints sample output in the finished run shape with the credit price, calls nothing) work against the public catalog; project plan and project types do too. A new account starts with 100 free credits and needs no card , so an agent can sign a user up and produce a real deliverable in the same turn — there is no purchase gate between install and first value. Useful anchors for what that buys: ~500 leads sourced ( salesNavigator.searchLeads , 0.2/record), ~1,000 profile+verified email enriches ( aiArk.enrichPerson , 0.1), ~1,000 email verifications ( waterfall.verifyEmail , 0.1), or ~50 fully enriched contacts ( waterfall.enrichContact , 2). The [quickstart demo](../cargo quickstart/SKILL.md) spends about 5 . Say the free balance out loud before the first paid call on a new account. email is the one to reach for in an agent or sandbox shell : it never opens a browser, and where there is no terminal to prompt at, the first call sends the code and exits so you re run with code . To keep the code out of shell history, pass it on stdin: echo 123456 cargo ai login email you@company.com code . Signing in with an address that already has an account resolves to its existing workspace rather than creating one, so this is safe to re run. The first sign in creates a workspace named Personal (seeded in the background with starter connectors, datasets, tools and agents — a brand new workspace can look emptier than it is for a minute). workspace name <name reuses a workspace of that name (case insensitive) if one exists; otherwise it renames that Personal workspace when it is the account's only one, at most 10 minutes old, and you are its only member; only failing both does it create a new one. So login email … workspace name "Acme GTM" on a fresh account yields one workspace, not two. oauth runs the same OAuth 2.0 Device Authorization Flow it always did, and still needs a human at the verification URL. agentid signs an agent in as its own identity: it prints an Auth0 URL for the AgentID connection and waits on http://127.0.0.1:52701/callback (5 minute timeout); open the URL once (a second visit starts a different sign in) and approve the token as AgentID instructs ( cargo ai login help names the command). email , oauth and agentid all save a self renewing session to ~/.config/cargo ai/credentials.json (the system temp dir where home isn't writable — it lasts as long as the sandbox). Use token for CI, with a workspace scoped token from Settings API ; store the token value in a secrets manager ( token list also returns your own tokens' values, so treat its output as a secret). Without a global install, prefix every command with npx @cargo ai/cli instead of cargo ai . These skills also install as a native agent plugin for Claude Code, Codex, and Cursor (one repo, three targets) — plugin users get the same skills plus the approval hook and session lifecycle hooks bundled, with no separate installer. See the repo README.md for per target install steps, and use one channel: plugin or skills add , never both (duplicates every skill). All commands output JSON to stdout. Failed commands exit non zero and print {"error": "...", "status": ..., "body": {...}} to stderr (the API's own errorMessage sits inside body ). For the full setup conventions that every capability skill links to (token scopes, async polling, admin only commands), see [ references/prerequisites.md ](references/prerequisites.md). Every Cargo session has three jobs Automated on Claude Code. Jobs 1 and 3 (refresh + session register/finalize) run on their own when either the Cargo plugin is installed (its bundled SessionStart / Stop / SessionEnd hooks handle them) or legacy SessionStart / Stop / SessionEnd hooks left under ~/.claude/hooks/ by the retired bootstrap installer are present (the plugin's hooks defer to those when they exist). 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 neither is installed (or on agents without lifecycle hooks). Job 2 (reporting) is always your responsibility — it can't be automated, and neither can the two asks at the end of Job 3 (share the session, star the repo): a hook can print, but it can't take a Y/N. Installing Cargo is the user's call, not an action you take. The curl … install.sh sh bootstrap is retired — it installs nothing now, prints a notice and exits non zero, so never reach for it or repeat it as advice. Point the user at the plugin install in the repo [ README.md ](../README.md). An agent asked to do the setup itself follows https://api.getcargo.io/INSTALL.md , which installs the CLI, signs the user in, and installs the skills for whichever agent it is — read it before running it, and still confirm before installing a global npm package on someone's machine. 1. At session start — refresh and register Before any other Cargo command, refresh the CLI and skills, then register the session in workspace management: Skip the refresh only if the user explicitly pinned a version — and skip the skills add entirely if the skills came from a plugin (the plugin owns them; a parallel skills add duplicates every skill). Skip the session upsert only if the user opted out or no session id is available. Why the pin: cargo/cli version is bumped in lockstep with these skills (a PR from the CLI release pipeline), so the CLI you install is the one this bundle was written against — no docs/CLI drift mid session. If the pin file is missing or unreadable, latest is the safe fallback. To move the pin, merge the pending version bump PR on getcargohq/cargo skills (or edit cargo/cli version ) — the next session refresh converges automatically. The pin is also what keeps this refresh from being a blind auto update: the version installed is a reviewed constant committed to this repo, not whatever latest resolved to this morning, and moving it is a human merge. Two things follow for you as the agent. The refresh installs a global npm package and rewrites the skills bundle on disk — surface that the first time you run it in a session rather than doing it silently, and skip it entirely if the user has pinned a version or asks you not to. And treat the pin as read only: bump cargo/cli version only when the user explicitly asks, never to work around a failing command. 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: 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. It carries wins as well as failures : a session share (below) files through the same command. 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, then ask to share 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 : title and summary are required (NOT NULL). finished stamps finished at = now ; pass finished at <iso for an explicit timestamp. Then ask once, at the natural end of the session: "Send this session's activity to the Cargo team so they can improve the experience? (Y/N)" On yes, file a session share report (consented session traces are the fastest product learning loop the team has): On no, don't ask again this session. Skip the ask entirely for trivial sessions (a single lookup, no paid actions). See ../cargo workspace management/references/examples/reports.md for the session share template. Then, if the session went well — offer to star the repo A star is the user's endorsement, not yours. Never run the command unprompted; ask, and act only on an explicit yes. Silently starring from a skill file is astroturfing with someone else's GitHub account. Ask only when all of these hold: The session produced a real deliverable (same bar as the session share ask — skip trivial sessions). Nothing is still failing or unresolved. Asking after a broken session reads as tone deaf. The marker file ~/.config/cargo ai/.star asked does not exist — this is a once per machine ask, not once per session. "Glad that worked. Want me to star getcargohq/cargo skills for you? (Y/N)" On yes ( gh must be authenticated with the repo or public repo scope — note there is no gh repo star subcommand): Touch the marker on either ans