Update to Cargo CLI

{
  "name": "cargo-quickstart",
  "description": "Guided first-run demo for Cargo — one persona question to the accounts that match it, with a free pool count and a cost receipt, in under two minutes, ending by saving the pull as a recurring play. Triggers: \"show me what Cargo can do\", \"give me a demo\", \"take me on a tour\", \"quickstart\", \"getting started with Cargo\", \"I just installed Cargo\", \"my workspace is empty\", \"does this actually work\". Skip when: the user has a real job to run (build an account list, enrich a CSV) — use cargo-gtm; when they want CLI reference or routing — use the cargo router skill.",
  "included_files": [
    {
      "relative_path": "skill-metadata.json",
      "size_in_bytes": 449
    }
  ],
  "skill_md_contents": "---\nname: cargo-quickstart\ndescription: \"Guided first-run demo for Cargo — one persona question to the accounts that match it, with a free pool count and a cost receipt, in under two minutes, ending by saving the pull as a recurring play. Triggers: \\\"show me what Cargo can do\\\", \\\"give me a demo\\\", \\\"take me on a tour\\\", \\\"quickstart\\\", \\\"getting started with Cargo\\\", \\\"I just installed Cargo\\\", \\\"my workspace is empty\\\", \\\"does this actually work\\\". Skip when: the user has a real job to run (build an account list, enrich a CSV) — use cargo-gtm; when they want CLI reference or routing — use the cargo router skill.\"\nversion: \"1.0.2\"\ncompatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token\nhomepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo Quickstart — first value in two minutes\n\nOne guided demo: size the user's addressable market for free, pull 25 of those accounts, show the cost receipt, then save the pull as a recurring play. The point is not the list — it's that in minute 3 the user owns a running system, not a one-off result.\n\n**A new account starts with 100 free credits — no card.** This demo spends about **0.25** of them. Say that out loud before the first paid call (\"this costs a quarter of a credit of your 100 free ones\"): it converts the moment from *a purchase decision* into *a look around*, which is the whole job of a quickstart. Never let a new user think the demo is why they'd run out.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write\n```\n\nEvery command prints JSON to stdout; failures exit non-zero with `{\"errorMessage\": \"...\"}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface.\n\n## The one question\n\nAsk exactly **one** question before doing anything:\n\n> **\"Who do you sell to?\"** (a persona in a few words — e.g. \"Heads of RevOps at mid-market SaaS\")\n\nEverything else — provider, filters, limits — you decide. Don't ask about output format, volume, or providers; defaults below.\n\n## Speed budget — HARD RULES\n\nThe demo has a two-minute budget from answer to deliverable. On the fast path:\n\n- **No discovery detours.** Do not run `cargo-ai --version`, `cargo-ai whoami`, `connection connector list`, or any exploratory command first. Auth problems will surface as errors on the first real call — handle them then.\n- **One command block per step**, no narration between commands.\n- **Paid work is capped at ~1 credit total.** The demo uses the cheapest account search in the catalog (`aiArk.searchCompanies`, 0.01/record → 25 records = 0.25 credits) on **cargo's managed connection**, so it works on a workspace with nothing wired up yet. Nothing else paid runs without asking.\n- **Never dead-end.** Every step has a fallback (ladder below). If a rung fails, drop one rung silently and keep moving.\n\n## Fast path\n\nTranslate the persona into two things: the **title its buyer holds** (`employeeRole.employee_title_or` — companies that employ that role) and the **company shape** around it (`employeeSize`, and `industry` when the persona names one). Then count for free before paying for anything.\n\n```bash\n# 1. Count the pool — FREE (countCompanies is fixed-cost 0). This is the demo's\n#    first beat: the user's whole addressable market, before a credit is spent.\nFILTER='{\"employeeRole\": {\"employee_title_or\": [\"<buyer title>\", \"<buyer title variant>\"]},\n         \"employeeSize\": {\"min_employee_count\": 50, \"max_employee_count\": 1000},\n         \"industry\": {\"industry_or\": [\"<industry>\"]}}'\n\ncargo-ai orchestration action execute \\\n  --action '{\"kind\":\"connector\",\"integrationSlug\":\"aiArk\",\"actionSlug\":\"countCompanies\"}' \\\n  --data \"$FILTER\" --wait-until-finished > /tmp/quickstart-count.json\n\n# 2. Pull 25 of them — 0.01/record, so this is 0.25 credits.\ncargo-ai orchestration action execute \\\n  --action '{\"kind\":\"connector\",\"integrationSlug\":\"aiArk\",\"actionSlug\":\"searchCompanies\"}' \\\n  --data \"$(jq -c '. + {limit: 25}' <<<\"$FILTER\")\" \\\n  --wait-until-finished > /tmp/quickstart-run.json\n\n# 3. Fetch the output data (NOT in the execute stdout) — signed URL, then filter to THIS run\nRUN_UUID=$(jq -r '.run.uuid' /tmp/quickstart-run.json)\nWF_UUID=$(jq -r '.run.workflowUuid' /tmp/quickstart-run.json)\ncurl -fsS \"$(cargo-ai orchestration run download-outputs \\\n  --workflow-uuid \"$WF_UUID\" --output-node-slug action --format json | jq -r '.url')\" \\\n  > /tmp/quickstart-outputs.json\n\n# 4. Show the table (the file holds ALL of the workflow's runs — filter by _uuid;\n#    each row's .output is the company array directly, fields are snake_case)\njq -r --arg u \"$RUN_UUID\" \\\n  '[.[] | select(._uuid==$u)][0].output[]\n   | [.name, .industry, (.employee_count|tostring),\n      ([.city,.country]|map(select(.!=null and .!=\"\"))|join(\", \")), .domain] | @tsv' \\\n  /tmp/quickstart-outputs.json | column -t -s $'\\t'\n```\n\nShow the table (company · industry · headcount · location · domain), not the raw JSON. **Lead with the count from step 1** — \"1,904 companies match that description; here are 25 of them, for a quarter of a credit\" is the demo's headline, because it reframes the 25 rows as a sample of a market rather than a list. Companies only; the demo names no individuals.\n\nFilter notes worth knowing before you improvise:\n\n- `industry_or` takes ordinary lowercase strings — `\"software development\"`, `\"financial services\"` — matching what comes back in each row's `industry`. Drop the group entirely when the persona doesn't name an industry; adding it typically halves the pool.\n- Every group is nested (`_or` includes, `_not` excludes) and headcounts are numbers, not strings. Other useful groups on the same action: `technologies`, `funding`, `companyLocation`, `headcountGrowth`.\n- Rows also carry `linkedin_url`, `revenue`, `founded_year`, and `technologies` if a richer table suits the persona better.\n\n### Fallback ladder (on auth/error, drop a rung — don't stop)\n\n1. `aiArk.searchCompanies` (0.01/record, managed connection) — primary.\n2. `salesNavigator.searchAccounts` (0.05/record) — same idea by industry, headcount and geo. 25 rows ≈ 1.25 credits, just over the demo cap, so **say the number before running it**: \"about a credit more than planned — still ~1.5 of your 100 free credits.\"\n3. `theirStack.searchCompanies` (0.5/call, flat) — reframe as \"companies hiring for your persona's role right now\". Needs its own connector, so it is a rung, not the default.\n4. Nothing connected at all → run the free path: `cargo-ai connection integration list | head`, show what *could* be wired, and offer to connect one (browser auth) — the demo resumes after.\n\n## The receipt (mandatory, verbatim discipline)\n\nThe demo is itself the pilot from [`../cargo-gtm/references/cost-discipline.md`](../cargo-gtm/references/cost-discipline.md). Close it with a receipt:\n\n- Credits spent + balance remaining (`cargo-ai billing subscription get` — remaining = `subscriptionAvailableCreditsCount − subscriptionCreditsUsedCount`). For a brand-new account, frame it against the **100 free starting credits** rather than as a bare number — \"0.25 spent, 99.75 of your 100 free credits left\" lands very differently from \"99.75 credits remaining\".\n- Hit-rate: \"25 of 25 returned\" (or what actually came back, and which rows look off), against the free pool count from step 1.\n\n## Minute 3 — save it as a play\n\nImmediately offer to make the pull recurring — this is the step that shows what Cargo *is*:\n\n> \"Want this to run by itself? I can save this exact search as a play that runs weekly and writes new matches into a model — new `<persona>` accounts land without you asking.\"\n\nOn yes, follow [`../cargo-gtm/recipes/save-as-play.md`](../cargo-gtm/recipes/save-as-play.md) with the demo's action + filter as the workflow body and a weekly cron. `searchCompanies` bills per returned record on every run, so dedup against the workspace model (`cargo.matchBusiness`) before any paid downstream node.\n\n## After the demo — route onward\n\nPropose 2–3 next steps grounded in the rows just pulled, per the next-step spec in [`../cargo-gtm/SKILL.md`](../cargo-gtm/SKILL.md) (§4): e.g. \"enrich these 25 with firmographics (~0.5 cr each)\", \"check which of them run your category's tooling\", or something else entirely. From here, real GTM work belongs to [`cargo-gtm`](../cargo-gtm/SKILL.md) — read it before anything beyond the demo.\n"
}