sc-finance-sync CLI

Repo: symphonycore-org/sc-finance-sync (private) CLI entry point: npm run <command> or docker exec sc-finance-sync npm run <command> Framework: Custom TypeScript scripts (tsx) Language: TypeScript (Node.js 20+)

Financial data synchronization between QuickBooks Online, Stripe, and Firefly III. Runs as a Docker container with scheduled cron jobs and supports manual invocation for ad-hoc syncs.

Commands

Command	Description	Docs
npm run sync:stripe	Sync Stripe transactions (payments, refunds, fees, payouts)	View
npm run sync:qbo	Sync QuickBooks Online bank transactions	View
npm run sync:all	Full daily sync pipeline (Stripe + QBO + matching + alerts)	View
npm run validate	E2E infrastructure health check (Docker, DB, HTTP, UI)	--

Arguments

The sync:stripe and sync:qbo commands accept optional date range arguments:

Argument	Description	Default
startDate	Start date (YYYY-MM-DD)	7 days ago
endDate	End date (YYYY-MM-DD)	Today

sync:qbo also accepts an optional accountId to filter to a specific QuickBooks account.

Typical Invocation

Local Development

npm run sync:stripe
npm run sync:qbo
npm run sync:all

Production (Docker)

docker exec sc-finance-sync npm run sync:stripe
docker exec sc-finance-sync npm run sync:all

Scheduled

The container runs sync:all automatically via node-cron at 6 AM daily (configurable via SYNC_CRON_SCHEDULE).

Prerequisites

• Node.js 20+ (local) or Docker (production)
• STRIPE_API_KEY -- Stripe secret key
• QBO_CLIENT_ID, QBO_CLIENT_SECRET, QBO_REALM_ID -- QuickBooks OAuth
• FIREFLY_API_TOKEN -- Firefly III personal access token
• DATABASE_URL -- PostgreSQL connection string
• API_KEY -- API authentication key (32+ characters)