Furlpay Cli

@furlpay/cli

Phase 5 hardening adds Windows DPAPI configuration encryption, durable payment retry keys and HTTPS-only directory links. See the implementation status and remaining integration requirements. Matching automatic payment requests reuse their saved key; use an explicit new --idempotency-key only for a separate payment after reconciling the previous one.

FurlPay's terminal client for reviewed account-to-account payments and freshness-aware financial monitoring.

The payment review follows the supplied dark fintech reference: mint confirmations, violet panels, rounded terminal geometry, a wide two-column profile and transfer layout, and responsive compact layouts. It adapts to TrueColor, 256-colour, basic ANSI, NO_COLOR, and narrow terminals.

Tech stack

Completion status

The terminal UI, monitoring client, Windows credential encryption, durable retry keys and HTTPS-only profile links are implemented. Production readiness is still incomplete: certificate pinning and request signatures, macOS Keychain/Linux Secret Service, backend quote and atomic settlement verification, production event feeds, and release signing remain open. See the Phase 5 status report for exact boundaries. Pushing this source does not publish an npm package or deploy the backend.

Install

Requires Node.js 22 or newer.

npm install -g @furlpay/cli

furlpay login

Payments

The executable flow fetches a new server quote, binds it to the reviewed recipient, amount, currency, source account, verification and sanctions decision, then asks for a single-key confirmation. The server remains the authority for authorization, fees, limits, balance and settlement.

# Safe, labelled offline recreation of the supplied reference. It never calls an API.

furlpay pay --demo

Authoritative quote review. This fetches current server data and never sends.

furlpay pay '@recipient' 10.00 USD --dry-run

Interactive terminal only: press y once the review screen is shown.

furlpay pay '@recipient' 10.00 USD

Scripted execution needs explicit intent and keeps a reconciliation key.

furlpay pay '@recipient' 10.00 USD --yes --idempotency-key invoice_20261029_001

PowerShell treats an unquoted @handle as a splat expression. Quote it as shown above. The CLI does not fabricate a recipient, quote, account balance, payment ID, or settlement outcome. If an execution request has an unknown outcome, it prints the idempotency key and requires reconciliation before a retry.

Live monitoring

Every monitor starts with the signed-in account's REST snapshot. It only displays LIVE after an authenticated event stream delivers authoritative, committed events with source and ingestion timestamps. REST-only values are marked UNKNOWN or DELAYED; data is hidden during SYNCING, STALE, and OFFLINE states.

furlpay dashboard --live

furlpay wallet balance --watch furlpay chains status --watch furlpay transactions --live furlpay directory '@recipient' --watch furlpay security monitor furlpay ledger --watch

The inspected backend exposes authenticated snapshots for wallets, transactions, chains, directory profiles, and selected admin data. It does not yet expose a general authenticated financial event feed, a Stripe payment feed, or an organisation-scoped customer feed. The CLI surfaces those gaps as UNKNOWN or OFFLINE rather than claiming live data. An SSE or WebSocket feed can be enabled with a same-origin endpoint:

furlpay dashboard --live --stream-path /api/events/stream --transport sse

furlpay dashboard --live --stream-path /api/events/ws --transport ws

The required event contract, source matrix, security controls, benchmarks, and failover evidence are in docs/cli.

Other commands

furlpay whoami

furlpay env sandbox furlpay balance --output json furlpay wallet address furlpay swap USDT USDC 100 --quote-only furlpay tx list furlpay invest portfolio furlpay travel search --city Tokyo --checkin 2026-12-01 --checkout 2026-12-05 furlpay card list furlpay earn furlpay completion bash|zsh|fish|powershell

MCP and AI clients

furlpay mcp

The MCP server exposes current, permission-scoped read tools and labels their freshness as UNKNOWN unless upstream provenance is available. It rejects financial mutations because a model must not manufacture payment approval. Use the interactive payment flow for payments.

{ "mcpServers": { "furlpay": { "command": "furlpay", "args": ["mcp"] } } }

Security model

• Session cookies are sent only to the configured same-origin API over HTTPS, except loopback sandbox HTTP.
• Terminal text from APIs is stripped of ANSI, OSC clipboard sequences, bidirectional overrides, hidden controls, and zero-width characters.
• Every payment checks a fresh authenticated quote before confirmation and again immediately before execution.
• Payment completion requires server-issued transaction evidence; a timeout, disconnect, approval, or pending state never becomes success.
• Event updates are subject- and organisation-scoped, sequenced, deduplicated, gap-detected, reconciled from a snapshot after reconnection, and size-limited.

Development

npm ci

npm run build npm test npm run docs:preview npm run benchmark

The package uses Node.js CommonJS and one audited runtime dependency, ws, for optional authenticated WebSocket subscriptions. CI tests Node 22 and 24 on Ubuntu, macOS, and Windows.

Local verification on 29 October 2026 (Windows, Node.js 26.7.0): build check passed; all 75 tests passed. This does not replace the Node 22/24 CI matrix or production integration verification.

Documentation

• Real-time architecture
• Authoritative data-source matrix
• Streaming security audit
• Measured local benchmarks
• Failover test evidence

License

MIT