money

README

money

A local-first, self-hostable personal finance backend for AI agents and power users.

---

What is money?

money pulls account and transaction data from user-configured financial providers, stores it in a user-owned encrypted SQLite database, and exposes stable CLI + JSON contracts for external agents, scripts, and cron jobs.

It does not embed AI chat, model providers, hosted billing, telemetry, or a required long-running server. Your data stays local. Your agent owns the reasoning.

Why

Existing personal finance tools either lock data behind a paid SaaS, embed opinionated AI advisors, or assume a full web-app product shape. money takes a different approach:

• Local-first data ownership — your financial data lives in an encrypted file you control.
• Agent-friendly contracts — stable JSON envelopes that any AI agent, script, or automation can parse.
• Provider-neutral — Plaid, Bridge, MX, Finicity, CSV imports — providers are replaceable adapters.
• No server required — runs as a CLI on your laptop, in cron, or in CI.

Quick Start

# Install
go install github.com/thedavidweng/money/cmd/money@latest

# Try it without real credentials
money demo accounts list --json

# Initialize configuration and encrypted database
money setup

# Configure a provider
money providers configure plaid --client-id ... --secret ... --environment sandbox

# Link and sync
money link
money sync
money accounts list --json
money transactions search "Costco" --json

Commands

money setup                         Initialize configuration and encrypted database
money doctor                        Check configuration and system health
money accounts list                 List financial accounts
money accounts create-manual        Create a local manual account
money transactions list             List transactions with filters
money transactions search           Search transactions by text
money categories list               List transaction categories
money tags list                     List transaction tags
money recurring list                List recurring transactions
money link                          Link a financial institution
money providers configure <provider> Configure provider credentials
money providers plaid link          Link a Plaid Provider Item
money providers bridge link         Link a Bridge Provider Item
money sync                          Sync linked provider data
money demo <command>                Run against non-persistent sample data
money version                       Print version

Read commands and provisional sync diagnostics support --json for machine-readable output. Manual write operations require --dry-run or --confirm.

Architecture

cmd/money/             CLI entrypoint (Cobra)
internal/contracts/    JSON envelopes, schema versions, error codes
internal/core/         Finance primitives and domain types
internal/providers/    Provider adapters (Plaid, Bridge, …)
internal/store/        Encrypted SQLite store and migrations
internal/config/       Configuration loading and validation

Read commands use local data only. Sync is the explicit boundary where outbound provider calls happen. See docs/ARCHITECTURE.md for the full design.

Design Principles

• CLI-first — human output by default, --json for automation.
• Stable contracts — versioned JSON envelopes with deterministic sorting and pagination.
• Explicit failures — no hidden fallbacks, no silent downgrades.
• BYOK providers — bring your own Plaid/Bridge credentials; no managed proxy or subscription.
• Encrypted at rest — real financial data never touches plaintext SQLite.
• Small deep modules — simple interfaces over pass-through wrappers.

Documentation

Document	Purpose
docs/PRD.md	Product requirements
docs/ARCHITECTURE.md	Module boundaries and data flow
docs/CONTRACTS.md	Current CLI JSON contracts
docs/SCHEMA.md	Database schema contract
docs/CONFIG.md	Configuration loading rules
docs/ROADMAP.md	Development phases

Website

The project landing page (Astro, static HTML) lives in website/. Published site: https://thedavidweng.github.io/money/ (enable GitHub Pages → GitHub Actions in the repository settings if it is not live yet).

cd website
npm ci
npm run dev    # local preview
npm run build  # output in website/dist

Acknowledgements

money draws inspiration from several excellent projects:

• monarchmoney-cli — agent-friendly CLI contract design, JSON envelope patterns, and safety model.
• Ray Finance — Plaid/Bridge sync architecture, local encrypted database patterns, and provider adapter design.
• Actual Budget — local-first budgeting philosophy and automation API patterns.
• Maybe Finance — personal finance domain modeling and product vocabulary.

License

MIT