Penny Pincer

Penny Pincer is an agent-friendly CLI for connecting a bank account with Plaid and reading account data as JSON.

npx penny-pincer auth
npx penny-pincer accounts
npx penny-pincer balances
npx penny-pincer transactions --days 30

Setup

The default CLI flow uses the hosted Penny Pincer backend:

npx penny-pincer auth

The backend creates Plaid Link tokens, exchanges public tokens, and proxies Plaid data requests. The CLI stores an encrypted token envelope and a local signing key at ~/.penny-pincer/config.json.

If you deploy your own backend, point the CLI at it:

export PENNY_PINCER_API_URL=https://your-vercel-app.vercel.app
npx penny-pincer auth

Production Plaid is the default for the hosted backend. For sandbox testing, pass --env sandbox:

npx penny-pincer auth --env sandbox

Commands

• penny-pincer auth opens Plaid Link, exchanges the public token through the backend, and saves local token metadata.
• penny-pincer accounts prints linked accounts.
• penny-pincer balances prints accounts with balances.
• penny-pincer transactions --days 30 prints recent transactions.
• penny-pincer identity prints account owner identity data when the product is enabled.
• penny-pincer numbers prints ACH/routing data when the Plaid auth product is enabled.
• penny-pincer status prints local connection metadata without exposing the access token.
• penny-pincer logout removes the saved local token.

All data commands print JSON so another agent or script can parse them directly.

Security Notes

The hosted backend stores your Plaid app credentials in Vercel environment variables. It does not need to store per-user Plaid access tokens. Instead, it returns an encrypted token envelope to the CLI. Data commands send that envelope back with a signed request; the backend decrypts the envelope just long enough to call Plaid.

Penny Pincer stores the encrypted envelope and a local private signing key in ~/.penny-pincer/config.json with 0600 file permissions. Treat that file like a password. If someone steals the full file, they can query data until you revoke the Plaid Item or rotate backend encryption keys.

Vercel Backend

Deploy this repository to Vercel and set:

PLAID_CLIENT_ID=your-client-id
PLAID_SECRET=your-secret
PLAID_SANDBOX_SECRET=your-sandbox-secret
PLAID_ENV=production
PLAID_REDIRECT_URI=https://penny-pincer.vercel.app/oauth-return
PENNY_PINCER_ENCRYPTION_KEY=at-least-32-random-bytes
PENNY_PINCER_TOKEN_KEY_VERSION=v1

Generate a strong encryption key with:

openssl rand -base64 32

The Vercel API exposes:

• POST /api/link-token
• POST /api/exchange
• POST /api/accounts
• POST /api/balances
• POST /api/transactions
• POST /api/identity
• POST /api/numbers

Bring Your Own Plaid App

You can still run the CLI without the hosted broker by using local Plaid credentials:

export PLAID_CLIENT_ID=your-client-id
export PLAID_SECRET=your-secret
export PLAID_ENV=sandbox
npx penny-pincer auth --direct-plaid

Development

npm install
npm run typecheck
npm run build
npm run dev -- status

Publishing is intentionally left to the package owner:

npm login
npm publish