Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,21 @@ All notable changes to moneyflow will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## [Unreleased]

### Added
- **YNAB support** - Full integration with You Need A Budget (editing, sync, categories)
- `--config-dir` option to specify custom configuration directory
- Nix flake for reproducible builds and installation
- Categories from backend now stored in `config.yaml` for local reference
- Green styling for positive amounts (credits) for visual distinction
- Right-justified dollar amounts with improved +/- sign placement

### Fixed
- Crash when quitting during credential screen
- Empty YNAB account (0 transactions) crash on load
- Error messages now show correct log file path when using `--config-dir`

## [0.5.3] - 2025-10-26

### Added
Expand Down
66 changes: 23 additions & 43 deletions docs/guide/monarch.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,36 @@
# Monarch Money Integration

**This guide is specifically for Monarch Money users.**

---
Terminal interface for Monarch Money with full editing and sync capabilities.

## Overview

moneyflow provides a powerful terminal interface for Monarch Money, allowing you to:

- View and analyze all your synced transactions
- Edit merchant names, categories, and other fields
- View and analyze synced transactions
- Edit merchants, categories, and transaction fields
- Hide/unhide transactions from reports
- Navigate by time periods, merchants, categories, and accounts
- Bulk edit transactions with multi-select
- Commit changes back to Monarch Money in real-time

All changes sync bidirectionally with your Monarch Money account.
- Navigate by time, merchant, category, and account
- Bulk edit with multi-select
- Real-time sync to Monarch Money

---

## Prerequisites

Before setting up moneyflow with Monarch Money, you'll need:

1. **Monarch Money account** - Active subscription required
2. **2FA secret key** - For automatic login (see below)
1. Active Monarch Money subscription
2. 2FA secret key (see below for setup)

---

## Getting Your 2FA Secret

!!! warning "Do this BEFORE running moneyflow"

1. Log into [Monarch Money](https://app.monarchmoney.com/)
2. Go to **Settings** → **Security**
3. **Disable** your existing 2FA
4. **Re-enable** 2FA
5. When shown the QR code, click **"Can't scan?"**
6. Copy the **BASE32 secret** (e.g., `JBSWY3DPEHPK3PXP`)
7. Save this somewhere secure (password manager recommended)
1. Log into [Monarch Money](https://app.monarchmoney.com/)
2. Go to **Settings** → **Security**
3. **Disable** existing 2FA, then **re-enable** it
4. Click **"Can't scan?"** when shown the QR code
5. Copy the BASE32 secret (e.g., `JBSWY3DPEHPK3PXP`)
6. Save to password manager

!!! info "Why do I need this?"
moneyflow requires your 2FA secret to automatically generate 6-digit codes for login.
This allows unattended operation and avoids manual code entry on every startup.
!!! info
moneyflow needs this secret to generate 2FA codes automatically for login.

---

Expand Down Expand Up @@ -74,21 +62,14 @@ Enter:

### 3. Create Encryption Password

moneyflow will ask you to create a **NEW password** to encrypt your stored credentials:

- This password is **only for moneyflow**, not for Monarch Money
- Choose something memorable - you'll need it every time you launch
- Minimum 8 characters recommended

!!! info "How Credentials Are Stored"
Your Monarch Money credentials are encrypted with AES-128 using PBKDF2 key derivation (100,000 iterations)
and stored at:
Create a NEW password to encrypt your stored credentials:

```
~/.moneyflow/credentials.enc
```
- Only for moneyflow (not your Monarch Money password)
- Needed every time you launch
- Minimum 8 characters

Only you can decrypt them with your encryption password.
!!! info
Credentials encrypted with AES-128/PBKDF2 (100k iterations) at `~/.moneyflow/credentials.enc`

### 4. Initial Data Load

Expand Down Expand Up @@ -183,8 +164,7 @@ See [CLI Options](../reference/cli.md) and [Caching](../config/caching.md) for d

## Data Privacy & Security

Your Monarch Money credentials are encrypted locally. moneyflow doesn't send data anywhere except Monarch Money.
See [Security Documentation](https://github.com/wesm/moneyflow/blob/main/SECURITY.md) for full details.
Credentials encrypted locally. Data only sent to Monarch Money. See [Security Documentation](https://github.com/wesm/moneyflow/blob/main/SECURITY.md).

---

Expand Down
114 changes: 24 additions & 90 deletions docs/guide/ynab.md
Original file line number Diff line number Diff line change
@@ -1,47 +1,36 @@
# YNAB Integration

**This guide is specifically for YNAB (You Need A Budget) users.**

---
Terminal interface for YNAB (You Need A Budget) with full editing and sync capabilities.

## Overview

moneyflow provides a powerful terminal interface for YNAB, allowing you to:

- View and analyze all your budgeted transactions
- Edit merchant names (payees), categories, and other fields
- Navigate by time periods, payees, categories, and accounts
- Bulk edit transactions with multi-select
- Commit changes back to YNAB in real-time

All changes sync bidirectionally with your YNAB account.
- View and analyze budgeted transactions
- Edit payees, categories, and transaction fields
- Navigate by time, payee, category, and account
- Bulk edit with multi-select
- Real-time sync to YNAB

---

## Prerequisites

Before setting up moneyflow with YNAB, you'll need:

1. **YNAB subscription** - Active You Need A Budget subscription required
2. **Personal Access Token** - For API authentication (see below)
1. Active YNAB subscription
2. Personal Access Token (see below for setup)

---

## Getting Your Personal Access Token

!!! warning "Generate token BEFORE running moneyflow"

1. Log into [YNAB](https://app.ynab.com/)
2. Go to **Account Settings** → **Developer Settings**
3. Under **Personal Access Tokens**, click **"New Token"**
4. Enter your YNAB password
5. Click **"Generate"**
6. **Copy the token immediately** - you won't be able to see it again
7. Save this somewhere secure (password manager recommended)
1. Log into [YNAB](https://app.ynab.com/)
2. Go to **Account Settings** → **Developer Settings**
3. Click **"New Token"** under Personal Access Tokens
4. Enter your YNAB password and click **"Generate"**
5. **Copy the token immediately** (you can't view it again)
6. Save to password manager

!!! info "Why do I need this?"
moneyflow uses YNAB's official API to access your budget data. Personal Access Tokens provide secure, long-lived
authentication without requiring your YNAB password.
!!! info
moneyflow uses YNAB's official API. Personal Access Tokens provide secure authentication without requiring your
YNAB password.

---

Expand Down Expand Up @@ -71,21 +60,14 @@ Enter:

### 3. Create Encryption Password

moneyflow will ask you to create a **NEW password** to encrypt your stored credentials:

- This password is **only for moneyflow**, not for YNAB
- Choose something memorable - you'll need it every time you launch
- Minimum 8 characters recommended
Create a NEW password to encrypt your stored credentials:

!!! info "How Credentials Are Stored"
Your YNAB Personal Access Token is encrypted with AES-128 using PBKDF2 key derivation (100,000 iterations) and
stored at:
- Only for moneyflow (not your YNAB password)
- Needed every time you launch
- Minimum 8 characters

```
~/.moneyflow/credentials.enc
```

Only you can decrypt it with your encryption password.
!!! info
Token encrypted with AES-128/PBKDF2 (100k iterations) at `~/.moneyflow/credentials.enc`

### 4. Initial Data Load

Expand Down Expand Up @@ -192,8 +174,7 @@ and [Caching](../config/caching.md) for details.

## Data Privacy & Security

Your YNAB credentials are encrypted locally. moneyflow uses YNAB's official REST API and doesn't send data anywhere
except YNAB. See [Security Documentation](https://github.com/wesm/moneyflow/blob/main/SECURITY.md) for full details.
Credentials encrypted locally. Data only sent to YNAB via official API. See [Security Documentation](https://github.com/wesm/moneyflow/blob/main/SECURITY.md).

---

Expand All @@ -217,50 +198,3 @@ Current limitations with YNAB integration:
- **No reconciliation**: Can't mark accounts as reconciled

These features may be added in future releases.

---

## YNAB API Rate Limits

YNAB's API has rate limits:

- **200 requests per hour** per access token
- moneyflow batches operations to minimize API calls
- Initial load: ~5-10 API calls
- Commit operations: 1 API call per batch

If you hit rate limits, wait an hour before making more requests.

---

## Differences from YNAB Web/Mobile App

moneyflow is optimized for **bulk operations** and **keyboard-driven workflows**:

| Feature | YNAB App | moneyflow |
|---------|----------|-----------|
| Navigation | Mouse/touch | Keyboard |
| Bulk edit | Limited | Unlimited multi-select |
| Search | Basic | Type-to-filter everywhere |
| Views | Budget-focused | Transaction-focused |
| Speed | Web UI delays | Instant local data |
| Editing | One at a time | Bulk with review |

Use moneyflow when you need to **clean up** lots of transactions quickly. Use YNAB's official apps for **budgeting**
and **planning**.

---

## YNAB Terminology in moneyflow

moneyflow uses generic terminology that maps to YNAB concepts:

| moneyflow Term | YNAB Term |
|----------------|-----------|
| Merchant | Payee |
| Category | Category |
| Group | Category Group |
| Account | Account |
| Amount | Amount (outflow negative, inflow positive) |

The UI displays "Merchant" but the underlying concept is YNAB's "Payee."
18 changes: 18 additions & 0 deletions docs/reference/changelog.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,23 @@
# Changelog

## Unreleased

**New:**

- **YNAB support** - Full integration with You Need A Budget
- `--config-dir` option for custom configuration directory
- Nix flake for reproducible builds
- Green styling for credits/refunds
- Right-justified dollar amounts

**Fixed:**

- Crash when quitting during credential screen
- Empty account (0 transactions) load error
- Log path in error messages when using `--config-dir`

---

## v0.5.3 - October 2025

**New:**
Expand Down
8 changes: 6 additions & 2 deletions scripts/generate_screenshots.py
Original file line number Diff line number Diff line change
Expand Up @@ -571,8 +571,12 @@ def _add_svg_dimensions(self, svg_path: Path):
# Extract viewBox dimensions
viewbox_match = re.search(r'viewBox="0 0 (\d+(?:\.\d+)?) (\d+(?:\.\d+)?)"', content)
if viewbox_match:
width = viewbox_match.group(1)
height = viewbox_match.group(2)
# Scale down by 35% (multiply by 0.65) to fit laptop screens better
original_width = float(viewbox_match.group(1))
original_height = float(viewbox_match.group(2))

width = int(original_width * 0.65)
height = int(original_height * 0.65)

# Add width and height attributes to svg tag
content = re.sub(
Expand Down