Update to Cargo CLI

{
  "name": "cargo-billing",
  "description": "Understand what Cargo is costing — remaining credits, usage broken down by workflow, connector, or agent, subscription state, and invoice history. Triggers: \"how many credits do I have left\", \"what did that cost\", \"why is my bill so high\", \"am I about to run out\", \"will this fit in our budget\", \"show me my invoices\", \"how much have I spent this month\", \"what plan am I on\", \"what do I get for free\", \"how many free credits\", \"can I afford this run\", \"add a card\", \"update my payment method\", \"why was my card declined\". Needs a token with admin access. Skip when: attributing spend to specific nodes or cutting a play cost — use cargo-diagnostics.",
  "included_files": [
    {
      "relative_path": "references/examples/usage-metrics.md",
      "size_in_bytes": 4067
    },
    {
      "relative_path": "references/response-shapes.md",
      "size_in_bytes": 3488
    },
    {
      "relative_path": "references/troubleshooting.md",
      "size_in_bytes": 3144
    },
    {
      "relative_path": "skill-metadata.json",
      "size_in_bytes": 792
    }
  ],
  "skill_md_contents": "---\nname: cargo-billing\ndescription: \"Understand what Cargo is costing — remaining credits, usage broken down by workflow, connector, or agent, subscription state, and invoice history. Triggers: \\\"how many credits do I have left\\\", \\\"what did that cost\\\", \\\"why is my bill so high\\\", \\\"am I about to run out\\\", \\\"will this fit in our budget\\\", \\\"show me my invoices\\\", \\\"how much have I spent this month\\\", \\\"what plan am I on\\\", \\\"what do I get for free\\\", \\\"how many free credits\\\", \\\"can I afford this run\\\", \\\"add a card\\\", \\\"update my payment method\\\", \\\"why was my card declined\\\". Needs a token with admin access. Skip when: attributing spend to specific nodes or cutting a play cost — use cargo-diagnostics.\"\nversion: \"1.1.0\"\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 CLI — Billing\n\nBilling and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/usage-metrics.md` for usage metric and subscription examples.\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`. **Admin-only:** every command in this skill requires a token with admin access on the workspace. Non-admin tokens return `{\"errorMessage\":\"forbidden\"}`. 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## Discover resources first\n\nUsage metrics can be filtered and grouped by resource UUID. Discover them before querying.\n\n```bash\ncargo-ai orchestration play list            # all plays (name, workflowUuid)\ncargo-ai orchestration tool list            # all tools (name, workflowUuid)\ncargo-ai ai agent list                     # all agents (uuid, name)\ncargo-ai connection connector list          # all connectors (uuid, name, integrationSlug)\ncargo-ai storage model list                # all models (uuid, name, slug)\n```\n\n## Quick reference\n\n```bash\ncargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD>\ncargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD> --group-by workflow_uuid\ncargo-ai billing subscription get\ncargo-ai billing subscription get-invoices\ncargo-ai billing subscription update-payment-method --card-number <number> --card-exp <MM/YYYY> --card-cvc <cvc>\ncargo-ai billing subscription create-portal-session\n```\n\n## Estimating cost before running a batch\n\nBefore triggering a large batch, estimate credit consumption to avoid unexpected charges.\n\n**Step 1 — Check current credit balance:**\n\n```bash\ncargo-ai billing subscription get\n# → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits\n```\n\n**Step 2 — Estimate cost from a sample run:**\n\nRun the workflow on a single record first and measure credits consumed:\n\n```bash\n# Run on one record\ncargo-ai orchestration run create --workflow-uuid <uuid> --data '{...}'\n# → poll to completion\n\n# Check credits used for that run\ncargo-ai billing usage get-metrics \\\n  --from <today> --to <today> \\\n  --workflow-uuid <uuid>\n# → .totalUsage = credits consumed today for this workflow\n```\n\n**Step 3 — Project batch cost:**\n\n```\nestimated_cost = credits_per_record × number_of_records\n```\n\nCompare against `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` before proceeding.\n\n**Step 4 — Monitor during the batch:**\n\n```bash\n# Check running costs mid-batch\ncargo-ai billing usage get-metrics \\\n  --from <start-date> --to <today> \\\n  --workflow-uuid <uuid>\n```\n\n**Cost levers:**\n\n| Action | Effect |\n|---|---|\n| Use a cheaper model (e.g. `gpt-4o-mini` vs `gpt-4o`) | Significant reduction for AI nodes |\n| Add `filter` nodes early in the graph | Skip ineligible records before expensive connector calls |\n| Set `fallbackOnFailure: false` | Stop the run early on failures instead of continuing to downstream nodes |\n| Reduce `maxSteps` on agent nodes | Limit how many tool calls an agent can make per record |\n\n> To find out **which** node or provider dominates a play's spend before picking a lever, follow the attribution runbook in [`../cargo-diagnostics/references/play-optimize-credits.md`](../cargo-diagnostics/references/play-optimize-credits.md).\n\n## Usage metrics\n\nPull credit and usage data for any time range, optionally filtered and grouped.\n\n```bash\n# Basic usage for a period\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date>\n\n# Group by dimension\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by workflow_uuid\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by connector_uuid\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by integration_slug\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by model_uuid\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by agent_uuid\n\n# Filter by specific resource\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date> --workflow-uuid <uuid>\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date> --agent-uuid <uuid>\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date> --connector-uuid <uuid>\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date> --integration-slug <slug>\n\n# Specify unit\ncargo-ai billing usage get-metrics --from <start-date> --to <end-date> --unit credits\n```\n\n`--group-by` values: `workflow_uuid`, `connector_uuid`, `model_uuid`, `integration_slug`, `agent_uuid`.\n\nAvailable filters: `--workflow-uuid`, `--model-uuid`, `--connector-uuid`, `--integration-slug`, `--slug`, `--agent-uuid`. Combine with `--group-by` and `--unit`.\n\n## Subscription and credits\n\n```bash\ncargo-ai billing subscription get                    # current plan, credits used/available, period dates\ncargo-ai billing subscription get-invoices            # invoice history (amounts in cents)\ncargo-ai billing subscription get-credit-card         # card on file\ncargo-ai billing subscription update-payment-method   # add or replace the card (see below)\ncargo-ai billing subscription create-portal-session   # Stripe portal URL for self-service billing\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` from `subscription get`.\n\n**Note:** Invoice amounts are returned in cents. Divide by 100 for the dollar value.\n\n### The free tier\n\nA new account starts with **100 free credits and no card on file**. When `subscription get` shows a fresh or near-fresh balance, answer cost questions against that budget rather than as an abstract number — \"you've used 12 of your 100 free credits\" is the useful answer to \"how am I doing?\", and it is also the honest one when the user is deciding whether to keep going.\n\nWhat 100 credits buys, as ballpark anchors (per-action costs in [`../cargo-gtm/references/credits-cost-table.md`](../cargo-gtm/references/credits-cost-table.md)):\n\n| Work | Cost | 100 credits ≈ |\n|---|---|---|\n| Source leads — `salesNavigator.searchLeads` | 0.02/record | ~5,000 leads |\n| Enrich from a LinkedIn URL + verified email — `aiArk.enrichPerson` | 0.1 | ~1,000 people |\n| Verify an email — `waterfall.verifyEmail` | 0.1 | ~1,000 checks |\n| Full contact enrichment — `waterfall.enrichContact` | 2 | ~50 contacts |\n| Find a phone — `FullEnrich.findPhone` | 6 | ~16 numbers |\n\nThe [quickstart demo](../cargo-quickstart/SKILL.md) spends about **0.5**. Phone lookups are the fastest way to burn a free tier, so phone is the **guarded lever**: the escalation tier runs 3–7 credits/record, ~10× email, and never belongs in a default chain — it enters a plan only on explicit user request, on qualified leads only. Full spend rules in [`../cargo-gtm/references/cost-discipline.md`](../cargo-gtm/references/cost-discipline.md).\n\n### Adding a card\n\nA workspace holds exactly one card. `update-payment-method` sets it, whether or not one is already on file, and takes the details three ways.\n\n```bash\n# Card details — no browser, nothing to hand off\ncargo-ai billing subscription update-payment-method \\\n  --card-number 4242424242424242 --card-exp 12/2030 --card-cvc 123\n\n# Same, but keeps the number out of shell history and the process list\necho '{\"number\":\"4242424242424242\",\"expMonth\":12,\"expYear\":2030,\"cvc\":\"123\"}' \\\n  | cargo-ai billing subscription update-payment-method --card-stdin\n\n# No card details — prints a Stripe-hosted form URL and waits for the card to land\ncargo-ai billing subscription update-payment-method\n```\n\n**Prefer `--card-stdin`.** Anything passed as a flag is visible in shell history and to any process that can read the process list. Card details go from your machine straight to Stripe in exchange for a token; they never reach the Cargo API, and no output prints them.\n\n**Never invent card details, and never reuse a number from elsewhere in the conversation.** Ask the user for them, or use the no-argument form and hand them the URL.\n\nThe no-argument form is the fallback when you have no details to submit: it prints a URL that opens directly on the card form, then polls until the card changes (`--timeout`, `--poll-interval`, `--no-open`). Relay that URL to the user — it works over SSH and in sandboxes.\n\nEither way the card is verified against the issuer before it becomes the default, so a card that cannot be charged fails here rather than silently at the next renewal.\n\n| Failure | What it means | What to do |\n|---|---|---|\n| `cardDeclined` + `declineCode` | The issuer refused the verification | Read `declineCode`. On a spend-limited virtual card, `insufficient_funds` or a limit code means the budget or merchant restrictions rule us out — ask the cardholder to raise it |\n| `authenticationRequired` | The card wants 3-D Secure, which needs the cardholder present | Re-run with no arguments and hand the user the hosted-form URL |\n| `paymentMethodNotFound` | The details did not resolve to a usable card | Re-check the number and expiry with the user |\n\nCard updates are rate-limited to **10 per hour per workspace** (shared with setup intents). Retrying a declined card burns that budget — fix the cause rather than looping.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai billing usage get-metrics --help\ncargo-ai billing subscription get --help\ncargo-ai billing subscription get-invoices --help\n```\n"
}