card-management

Non-Negotiables

• To list cards, use ramp cards list — NOT ramp funds list (that lists funds/budgets, not cards).
• The API has no server-side state filter. To count or filter by state, list all cards, then filter on card_state client-side.
• Pass --agent for machine-readable JSON output whenever you need to count or filter programmatically.
• card_state is a free-form string from the API with no fixed enum in the spec; active cards report a card_state that equals active case-insensitively (e.g. ACTIVE). Always compare case-insensitively and report exactly what the API returns; do not invent states.
• A card's lifecycle state (card_state) is distinct from its activation_status (whether the physical card has been activated). A card can be active while still not_activated for physical use.

Workflow

Step 1: List the cards

ramp cards list --rationale "list the user's cards" --agent

In --agent mode the response is wrapped in the standard envelope: the cards live in the nested array at .data[0].cards[] (not one card per .data[]). Each card object includes display_name, last_four, card_state, activation_status, card_type, is_physical, and id.

Admins and managers can target another employee's cards by passing that user's UUID — run ramp cards list --help to confirm the option is available in your synced spec.

Step 2: Count or filter by state

Count active cards directly with jq. The cards are at .data[0].cards[], and card_state casing is compared case-insensitively so it works regardless of how the API capitalizes it:

ramp cards list --rationale "count active cards" --agent | jq '[.data[0].cards[] | select((.card_state // "" | ascii_downcase) == "active")] | length'

List just the active card names:

ramp cards list --rationale "list active cards" --agent | jq -r '.data[0].cards[] | select((.card_state // "" | ascii_downcase) == "active") | .display_name'

In a human terminal, ramp cards list shows card_state and activation_status as columns, so you can count active cards by eye.