npm package: @flowglad/pay-cli
Description: CLI and API client for Flowglad Pay
Latest version: 0.6.0

# @flowglad/pay-cli

CLI for [Flowglad Pay](https://flowgladpay.com) — manage virtual payment cards, card sessions, and payment methods.

## Installation

```bash
npm install -g @flowglad/pay-cli
```

## Setup

```bash
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.

```bash
fgp login
```

### `fgp logout`

Revoke tokens and delete local credentials.

```bash
fgp logout
```

### `fgp whoami`

Show current auth status.

```bash
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.

```bash
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).

```bash
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.

```bash
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).

```bash
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.

```bash
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.

```bash
fgp card session-redemptions cs_abc123
fgp card session-redemptions cs_abc123 --json
```

---

### `fgp payment-methods list`

```bash
fgp payment-methods list
fgp payment-methods list --json
```

### `fgp payment-methods get <id>`

```bash
fgp payment-methods get pm_abc123
fgp payment-methods get pm_abc123 --json
```

---

## Programmatic client

```ts
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