@flowglad/pay-cli

CLI for Flowglad Pay — manage virtual payment cards, card sessions, and payment methods.

Installation

npm install -g @flowglad/pay-cli

Setup

fgp login                                          # authenticate via the browser (device flow)
export FGP_API_ENDPOINT=https://your-host/api      # optional — defaults to https://app.flowgladpay.com/api

Commands

fgp login

Authenticate via the browser using a device flow.

fgp login

fgp logout

Revoke tokens and delete local credentials.

fgp logout

fgp whoami

Show current auth status.

fgp whoami

fgp card use

Create a card session request with spend intent, poll for approval, and redeem — returning card details in one step.

Security: This command outputs full card details. Treat stdout as PCI-sensitive: do not paste it into logs, tickets, chat, or terminal recordings. Only use --json when stdout is being consumed securely by the next process.

fgp card use --amount 1500 --merchant "example.com"
fgp card use --amount 1500 --merchant "AWS" --payment-method-id pm_abc123
fgp card use --amount 1500 --merchant "example.com" --json

Flags

| Flag | Default | Description | |------|---------|-------------| | --amount <cents> | (required) | Spend amount in cents (e.g., 1500 for $15) | | --merchant <name> | (required) | Merchant name or domain | | --payment-method-id <id> | auto | Payment method ID to use | | --currency <code> | USD | ISO 4217 currency code | | --merchant-category <code> | | Merchant category code (MCC) | | --description <text> | | Description of the purchase | | --poll-interval <seconds> | 3 | Approval poll interval (1-60) | | --json | false | Output as JSON |

fgp card request

Create a card session request with spend intent (returns request ID for manual approval workflow).

fgp card request --amount 1500 --merchant "example.com"
fgp card request --amount 1500 --merchant "example.com" --ttl 600 --max-redemptions 3
fgp card request --amount 1500 --merchant "example.com" --json

Flags

| Flag | Default | Description | |------|---------|-------------| | --amount <cents> | (required) | Spend amount in cents | | --merchant <name> | (required) | Merchant name or domain | | --payment-method-id <id> | auto | Payment method ID to use | | --currency <code> | USD | ISO 4217 currency code | | --merchant-category <code> | | Merchant category code (MCC) | | --description <text> | | Description of the purchase | | --ttl <seconds> | 300 | Session TTL in seconds (30-3600) | | --max-redemptions <n> | 1 | Max number of redemptions (1-10) | | --json | false | Output as JSON |

fgp card get-session <session-id>

Get card session details.

fgp card get-session cs_abc123
fgp card get-session cs_abc123 --json

fgp card get-request <request-id>

Check the status of a card session request (pending, approved, denied, expired).

fgp card get-request csr_abc123
fgp card get-request csr_abc123 --json

fgp card redeem-session <session-id>

Redeem a card session to retrieve card details (number, expiry, CVC).

Security: Redemption output contains full card details. Avoid logging or persisting stdout, and only use --json when piping directly into a secure consumer. Treat the redeem token as secret as well: anyone with the token can redeem the session until it expires or reaches its redemption limit. Do not log, persist, or share it.

fgp card redeem-session cs_abc123 --token <redeem-token>
fgp card redeem-session cs_abc123 --token <redeem-token> --json

fgp card session-redemptions <session-id>

List all redemptions for a card session.

fgp card session-redemptions cs_abc123
fgp card session-redemptions cs_abc123 --json

fgp payment-methods list

fgp payment-methods list
fgp payment-methods list --json

fgp payment-methods get <id>

fgp payment-methods get pm_abc123
fgp payment-methods get pm_abc123 --json

Programmatic client

import { createFgpClient } from '@flowglad/pay-cli/client'

const fgp = createFgpClient({
  endpoint: 'https://app.flowgladpay.com/api',
  accessToken: '...', // JWT from `fgp login`
})

// Card session requests — request access to card details with spend intent
const result = await fgp.createCardSessionRequest({
  paymentMethodId: 'pm_...',
  spendIntent: { amountCents: 1500, merchant: 'example.com', currency: 'USD' },
  ttlSeconds: 300,
  maxRedeemCount: 1,
})
// result.outcome is 'auto_approved' or 'pending_approval'

// Check request status (if pending approval)
const request = await fgp.getCardSessionRequest(result.requestId)

// Redeem to get card details once approved
const card = await fgp.redeemCardSession(result.session.id, result.redeemToken)
// `redeemToken` is secret; keep it in memory only.
// Use card details directly in your payment flow — never log PAN/CVC

const sessionInfo = await fgp.getCardSession(result.session.id)
const { redemptions } = await fgp.listCardSessionRedemptions(result.session.id)

License

MIT