moneyflow 0.8.1

Track your moneyflow - A powerful terminal UI for personal finance management

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
• ✅ 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

# 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.

---

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
• Amazon Mode

---

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

Security reviews:

All PRs from external contributors are automatically reviewed by Claude for security issues. See Security Bot Documentation for details.

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.