Cargo

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

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, cdk, 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 defines the whole workspace as code (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` for term-by-term definitions (UUIDs, slugs, conjonction, run/batch/play/tool, signal/persona/ICP, etc.).

Interaction conventions: See `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

npm install -g @cargo-ai/cli

# Recommended: emailed code, no browser at any point.
# Creates the account and a workspace on first use — there is no separate sign-up step.
cargo-ai login --email you@company.com            # sends the code, then exits
cargo-ai login --email you@company.com --code 123456

# Alternatives
cargo-ai login --oauth                            # browser sign-in (OAuth device flow)
cargo-ai login --token <your-api-token>           # existing workspace-scoped API token (CI)

# Optional: pick the workspace at login instead of being prompted
cargo-ai login --email you@company.com --workspace-name "Acme GTM"

# Verify
cargo-ai whoami

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: ~5,000 leads sourced (salesNavigator.searchLeads, 0.02/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 spends about 0.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.

--oauth runs the same OAuth 2.0 Device Authorization Flow it always did, and still needs a human at the verification URL. Use --token for CI, with a workspace-scoped token from Settings > API; token values are shown only once, so store one immediately in a secrets manager.

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 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 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`. 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:

# Refresh — idempotent, ~10s. Skills first, then the CLI at the version the
# bundle pins. The pin file `cli-version` sits in the same directory as this
# SKILL.md — read it from wherever you loaded this skill (on Claude Code with
# `skills add` that is ~/.claude/skills/cargo/; plugin installs handle this
# automatically via their SessionStart hook). Fall back to latest.
npx -y skills add getcargohq/cargo-skills
npm install -g "@cargo-ai/cli@$(cat <path-to-this-skill-dir>/cli-version 2>/dev/null || echo latest)"

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