| name | card-management |
| description | List a user's cards and count or filter them by state (e.g. how many are active),
then activate or lock/unlock a card from the terminal.
Use when: 'list my cards', 'how many cards', 'how many active cards', 'count active cards',
'which cards are active', 'show my cards', 'card status', 'activate my card',
'lock my card', 'unlock my card', 'is my card active'.
Do NOT use for: listing funds/budgets or spend allocations (use `ramp funds list`),
agent card payments (use agentic-purchase), or transaction history (use spend-analysis). |
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.
Step 3 (optional): Activate or lock a card
Activate a physical card by its last four digits:
ramp cards activate --last_four 1234 --rationale "activate the user's new physical card" --agent
Lock or unlock a card by its id (the id field from cards list) — the id is a required positional argument:
ramp cards lock 7f3c0d2a-9b1e-4a55-8c21-0e9d6b2f4a10 --action lock --rationale "user lost their card" --agent
ramp cards lock 7f3c0d2a-9b1e-4a55-8c21-0e9d6b2f4a10 --action unlock --rationale "user found their card" --agent
The same tools are also available under funds (ramp funds list-cards, ramp funds activate, ramp funds lock-or-unlock-card) — cards <alias> is a convenience alias for the same endpoints.
Fields Available (from cards list)
| Field | Description |
|---|
display_name | Card name |
last_four | Last four digits |
card_state | Lifecycle state; equals active (case-insensitive, e.g. ACTIVE) when the card is active |
activation_status | Whether the physical card has been activated |
card_type | Virtual or physical card type |
is_physical | Whether the card is a physical card |
is_locked | Whether the card is currently locked |
id | Card UUID |
Example Session
User: How many active cards do I have?
Agent: > ramp cards list --rationale "count active cards" --agent | jq '[.data[0].cards[] | select((.card_state // "" | ascii_downcase) == "active")] | length'
3
You have 3 active cards.
Gotchas
| Issue | Fix |
|---|
ramp funds list returns funds/budgets, not cards | Use ramp cards list to list cards |
No --state/--active flag exists | List all cards and filter on card_state client-side |
card_state casing varies | Compare case-insensitively (ascii_downcase in jq) |
| Something broken? | ramp feedback "message" to report CLI/API bugs |
