Quick start

This gets Subsweep running on your laptop. You need Node.js 20.9 or newer (22 recommended) and npm. Nothing else is required for a first look.

1. Install and start#

From the folder you unzipped:

npm install
cp .env.example .env.local
npm run dev

Open http://localhost:3000 (or the port Next.js prints if 3000 is taken).

2. Look around with the demo shop#

The sign-in page offers a one-click Northwind Studio demo. It creates a sample workspace with subscriptions, flags, savings and team members, so you can see every screen with data in it.

In development the demo button is on unless DEMO_LOGIN_ENABLED=false. In production it is off unless you set DEMO_LOGIN_ENABLED=true, because its password is public; see The demo account.

3. Create your own account#

Sign up at /signup with any email and a password of at least 10 characters. In development:

• No email verification is required, and no email is sent unless you configure SMTP or Resend.
• Magic links are printed in the terminal running npm run dev, on a line starting with [subsweep] Magic link for.
• New workspaces start on a 14-day Pro trial, so every feature is unlocked.

Production is stricter: without SMTP or Resend it refuses email sign-up and magic links (Configuration).

Onboarding asks for company size and monthly software spend, then country, timezone and when to send the digest. The country decides the base currency and which bank provider is offered.

4. Add subscriptions#

From Sources (or the first-session flow):

1. Add by hand or use the quick-add checklist of 48 common tools.
2. Upload a statement (CSV, XLSX or a text-layer PDF). Known Indian bank formats and Relay statements are recognised; anything else gets a column mapper.
3. Connect bank or Scan email. Without Plaid, Gmail or Outlook keys, development uses built-in sample transactions instead, so you can watch detection work.

After a scan, the Reveal screen shows estimated savings, then the subscription list. Adding and detecting subscriptions explains what each source does.

5. Run the hourly job by hand#

Reminders, alerts and digests come from one job that a scheduler calls every hour. Nothing calls it under npm run dev. To run it once locally (no secret is needed in development):

curl http://localhost:3000/api/jobs/tick

Without email configured, each email the job would send is logged as a [subsweep] Email to ... line instead.

6. Use a real Postgres (optional)#

The bundled docker-compose.yml starts Postgres 16 with user, password and database all named subsweep:

docker compose up -d

DATABASE_URL=postgres://subsweep:subsweep@localhost:5432/subsweep

Restart npm run dev. The tables are created automatically on first use; there is no migration command to run.

7. Turn on real integrations (optional)#

Add keys to .env.local and restart. A few useful ones for local testing:

# Outbound email through Gmail SMTP (an app password, not your account password)
SMTP_USER=you@gmail.com
SMTP_PASS=your-app-password

# Google sign-in; redirect URI http://localhost:3000/api/auth/callback/google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Stripe test mode. Plans change only when a signed webhook arrives, for example
# from: stripe listen --forward-to localhost:3000/api/webhooks/stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Configuration lists every variable, and Integrations has each provider's redirect URI.

Checks the package ships with#

npm test          # Vitest: detection, statement parsing, sign-up, billing and bank return rules (79 tests)
npm run lint      # ESLint
npm run typecheck # tsc --noEmit

Next steps#

• Installation and deployment for a real server or Vercel.
• Configuration for every variable and its default.