cargo-billing

Cargo CLI — Billing

Billing and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.

See references/response-shapes.md for full JSON response structures. See references/troubleshooting.md for common errors and how to fix them. See references/examples/usage-metrics.md for usage metric and subscription examples.

Bootstrap

Already signed in (cargo-ai whoami returns a workspace)? Skip to the next section.

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token  (CI)
cargo-ai whoami                         # confirm the active workspace before any write

Every 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 adds the CLI version pin, token scopes, and the admin-only surface.

Discover resources first

Usage metrics can be filtered and grouped by resource UUID. Discover them before querying.

cargo-ai orchestration play list            # all plays (name, workflowUuid)
cargo-ai orchestration tool list            # all tools (name, workflowUuid)
cargo-ai ai agent list                     # all agents (uuid, name)
cargo-ai connection connector list          # all connectors (uuid, name, integrationSlug)
cargo-ai storage model list                # all models (uuid, name, slug)

Quick reference

cargo-ai billing usage get-metrics --from  --to 
cargo-ai billing usage get-metrics --from  --to  --group-by workflow_uuid
cargo-ai billing subscription get
cargo-ai billing subscription get-invoices
cargo-ai billing subscription update-payment-method --card-number  --card-exp  --card-cvc 
cargo-ai billing subscription create-portal-session

Estimating cost before running a batch

Before triggering a large batch, estimate credit consumption to avoid unexpected charges.

Step 1 — Check current credit balance:

cargo-ai billing subscription get
# → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits

Step 2 — Estimate cost from a sample run:

Run the workflow on a single record first and measure credits consumed:

# Run on one record
cargo-ai orchestration run create --workflow-uuid  --data '{...}'
# → poll to completion

# Check credits used for that run
cargo-ai billing usage get-metrics \
  --from  --to  \
  --workflow-uuid 
# → .totalUsage = credits consumed today for this workflow

Step 3 — Project batch cost:

estimated_cost = credits_per_record × number_of_records

Compare against subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount before proceeding.

Step 4 — Monitor during the batch:

# Check running costs mid-batch
cargo-ai billing usage get-metrics \
  --from  --to  \
  --workflow-uuid 

Cost levers:

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.

Usage metrics

Pull credit and usage data for any time range, optionally filtered and grouped.

# Basic usage for a period
cargo-ai billing usage get-metrics --from  --to 

# Group by dimension
cargo-ai billing usage get-metrics --from  --to  --group-by workflow_uuid
cargo-ai billing usage get-metrics --from  --to  --group-by connector_uuid
cargo-ai billing usage get-metrics --from  --to  --group-by integration_slug
cargo-ai billing usage get-metrics --from  --to  --group-by model_uuid
cargo-ai billing usage get-metrics --from  --to  --group-by agent_uuid

# Filter by specific resource
cargo-ai billing usage get-metrics --from  --to  --workflow-uuid 
cargo-ai billing usage get-metrics --from  --to  --agent-uuid 
cargo-ai billing usage get-metrics --from  --to  --connector-uuid 
cargo-ai billing usage get-metrics --from  --to  --integration-slug 

# Specify unit
cargo-ai billing usage get-metrics --from  --to  --unit credits

--group-by values: workflow_uuid, connector_uuid, model_uuid, integration_slug, agent_uuid.

Available filters: --workflow-uuid, --model-uuid, --connector-uuid, --integration-slug, --slug, --agent-uuid. Combine with --group-by and --unit.

Subscription and credits

cargo-ai billing subscription get                    # current plan, credits used/available, period dates
cargo-ai billing subscription get-invoices            # invoice history (amounts in cents)
cargo-ai billing subscription get-credit-card         # card on file
cargo-ai billing subscription update-payment-method   # add or replace the card (see below)
cargo-ai billing subscription create-portal-session   # Stripe portal URL for self-service billing

Remaining credits = subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount from subscription get.

Note: Invoice amounts are returned in cents. Divide by 100 for the dollar value.

The free tier

A 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.

What 100 credits buys, as ballpark anchors (per-action costs in ../cargo-gtm/references/credits-cost-table.md):

The quickstart demo 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.

Adding a card

A workspace holds exactly one card. update-payment-method sets it, whether or not one is already on file, and takes the details three ways.

# Card details — no browser, nothing to hand off
cargo-ai billing subscription update-payment-method \
  --card-number 4242424242424242 --card-exp 12/2030 --card-cvc 123

# Same, but keeps the number out of shell history and the process list
echo '{"number":"4242424242424242","expMonth":12,"expYear":2030,"cvc":"123"}' \
  | cargo-ai billing subscription update-payment-method --card-stdin

# No card details — prints a Stripe-hosted form URL and waits for the card to land
cargo-ai billing subscription update-payment-method

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.

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.

The 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.

Either 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.

Card 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.

Help

Every command supports --help:

cargo-ai billing usage get-metrics --help
cargo-ai billing subscription get --help
cargo-ai billing subscription get-invoices --help