wesm/moneyflow

moneyflow

Track your moneyflow from the terminal.

A keyboard-driven terminal UI for managing personal finance transactions. Built for users who prefer efficiency and direct control over their financial data.

Supported Platforms:

• ✅ Monarch Money - Full integration with editing and sync
• ✅ YNAB - Full integration with editing and sync
• ✅ Amazon Purchases - Import and analyze purchase history
• ✅ CSV Import - Import transactions from bank CSV exports
• ✅ SimpleFIN - Import read-only account and transaction data; edits remain local
• ✅ Demo Mode - Try it without an account

Documentation: moneyflow.dev

Installation

# Install with pip
pip install moneyflow

# Or run without installing (recommended)
uvx moneyflow

# Or use pipx
pipx install moneyflow

Quick Start

# Try demo mode first (no account needed)
moneyflow --demo

# Connect to Monarch Money or YNAB
moneyflow

# Analyze Amazon purchase history
moneyflow amazon import ~/Downloads/"Your Orders"
moneyflow amazon

# Import bank CSV exports
moneyflow import institution chase_credit ~/Downloads/
moneyflow chase_credit

# Fetch only recent data from API (Monarch/YNAB only - for faster loading)
moneyflow --year 2025  # Fetch from 2025-01-01 onwards
moneyflow --since 2024-06-01  # Fetch from specific date

First-time Monarch Money setup: You'll need your 2FA secret key. See the Monarch Money setup guide.

First-time YNAB setup: You'll need a Personal Access Token from your YNAB account settings. If you have multiple budgets, you'll be prompted to select one. See the YNAB setup guide.

Key Features

• Keyboard-driven - Navigate with g to cycle views, Enter to drill down, Escape to go back
• Multi-select bulk editing - Select with Space, edit with m/c/h, commit with w
• Multiple aggregation dimensions - Merchants, Categories, Groups, Accounts, Time (by year/month)
• Drill-down and sub-grouping - Analyze spending from multiple angles, combine dimensions
• Type-to-search - Filter transactions as you type with /
• Review before commit - Preview all changes before syncing to backend
• Encrypted credentials - AES-128 with PBKDF2 (100,000 iterations)

Full keyboard shortcuts and tutorials: moneyflow.dev

Common Workflows

Clean up merchant names:

1. Press g until Merchant view
2. Press m on a merchant to rename all transactions
3. Press w to review and commit

Recategorize transactions:

1. Press d for detail view
2. Press Space to multi-select transactions
3. Press c to change category
4. Press w to review and commit

Analyze spending:

1. Press g to cycle views (Merchants → Categories → Groups → Accounts → Time)
2. In Time view: Press t to cycle granularity (Year → Month → Day), Enter to drill into a period
3. In any aggregate view: Press Enter to drill down
4. Press g to cycle sub-groupings (including by Time)
5. Press a to clear time drill-down, Escape to go back

Learn more: Navigation & Search Guide

Amazon Mode

Import and analyze your Amazon purchase history:

1. Request "Your Orders" export from Amazon (Account Settings → Privacy)
2. Download and unzip "Your Orders.zip"
3. Import: moneyflow amazon import ~/Downloads/"Your Orders"
4. Launch: moneyflow amazon

See Amazon Mode Guide for details.

CSV Import Mode

Import transaction histories from bank CSV exports:

1. Download CSV export from your bank or credit card website
2. Import: moneyflow import institution chase_credit ~/Downloads/
3. Launch: moneyflow chase_credit

List supported institutions: moneyflow import list

See CSV Import Guide for details.

Troubleshooting

Login fails with "Incorrect password"

• Enter your encryption password (for moneyflow), not your backend password
• If forgotten: Click "Reset Credentials" or delete ~/.moneyflow/

Monarch Money - 2FA not working

• Copy the BASE32 secret (long string), not the QR code
• Get fresh secret: Disable and re-enable 2FA in Monarch Money

YNAB - Connection fails

• Verify your Personal Access Token is correct
• Token may have expired - generate a new one from YNAB Developer Settings
• Make sure you copied the entire token (no spaces before/after)
• Token is only shown once - if lost, generate a new one

Terminal displays weird characters

• Use a modern terminal with Unicode support (iTerm2, GNOME Terminal, Windows Terminal)

Complete reset

rm -rf ~/.moneyflow/
pip install --upgrade --force-reinstall moneyflow
moneyflow

More help: Troubleshooting Guide

Themes

moneyflow includes multiple color themes for different aesthetic preferences:

• default - Original moneyflow dark theme
• berg - Orange on black (inspired by Bloomberg Terminal) - nostalgic 1980s financial terminal aesthetic
• nord - Nord (arctic blue tones) - popular among developers for eye-friendly cool colors
• gruvbox - Gruvbox (retro warm colors) - vintage aesthetic beloved by vim users
• dracula - Dracula (modern purple) - vibrant high-contrast dark theme
• solarized-dark - Solarized Dark (precision colors) - scientifically designed for reduced eye strain
• monokai - Monokai (Sublime Text classic) - the iconic editor theme

Configuring Themes

Set your preferred theme in ~/.moneyflow/config.yaml:

version: 1

settings:
  theme: berg  # or nord, gruvbox, dracula, solarized-dark, monokai

Restart moneyflow for the theme to take effect.

Documentation

Full documentation available at moneyflow.dev

• Installation
• Quick Start Tutorial
• Navigation & Search
• Editing Transactions
• Keyboard Shortcuts
• Monarch Money Setup
• YNAB Setup
• SimpleFIN Setup
• Amazon Mode
• CSV Import

Security

• Credentials encrypted with AES-128 using PBKDF2 key derivation (100,000 iterations)
• Encryption password never leaves your machine
• Stored in ~/.moneyflow/credentials.enc with 600 permissions
• See SECURITY.md for full details

Contributing

Contributions welcome! See Contributing Guide.

Development setup:

git clone https://github.com/wesm/moneyflow.git
cd moneyflow
uv sync
uv run pytest -v

Code quality checks:

uv run pytest -v                          # Tests
uv run pyright moneyflow/                 # Type checking
uv run ruff format moneyflow/ tests/      # Formatting
uv run ruff check moneyflow/ tests/       # Linting

See Developing moneyflow for details.

Acknowledgments

Monarch Money Integration

This project's Monarch Money backend uses code derived from the monarchmoney Python client library by hammem, used under the MIT License. See licenses/monarchmoney-LICENSE for details.

Monarch Money® is a trademark of Monarch Money, Inc. This project is independent and not affiliated with, endorsed by, or officially connected to Monarch Money, Inc.

License

MIT License - see LICENSE file for details.

Disclaimer: Independent open-source project. Not affiliated with or endorsed by Monarch Money, Inc. or YNAB LLC.