monarch-money

# Monarch Money

CLI and TypeScript library for Monarch Money budget automation.

## Prerequisites

### Environment Variables (Required)

| Variable | Required | Description |
|----------|----------|-------------|
| `MONARCH_EMAIL` | **Yes** | Monarch Money account email |
| `MONARCH_PASSWORD` | **Yes** | Monarch Money account password |
| `MONARCH_MFA_SECRET` | **Yes** | TOTP secret for MFA (see below) |

### Getting Your MFA Secret

Monarch Money requires MFA. Generate the TOTP secret:

1. Login to https://app.monarchmoney.com
2. Go to Settings > Security > Two-Factor Authentication
3. If MFA is already enabled: disable and re-enable to get a new secret
4. When shown the QR code: click "Can't scan? View setup key"
5. Copy the secret key (base32 string like `JBSWY3DPEHPK3PXP`)
6. Complete MFA setup in Monarch Money with an authenticator app
7. Set the secret: `export MONARCH_MFA_SECRET="YOUR_SECRET"`

## Quick Start

```bash
# Check setup
monarch-money doctor

# Login (uses env vars by default)
monarch-money auth login

# List transactions
monarch-money tx list --limit 10

# List categories
monarch-money cat list
```

## CLI Commands

### Authentication

```bash
# Login with environment variables
monarch-money auth login

# Login with explicit credentials
monarch-money auth login -e email@example.com -p password --mfa-secret SECRET

# Check auth status
monarch-money auth status

# Logout
monarch-money auth logout
```

### Transactions

```bash
# List recent transactions
monarch-money tx list --limit 20

# Search by date
monarch-money tx list --start-date 2026-01-01 --end-date 2026-01-31

# Search by merchant
monarch-money tx list --merchant "Walmart"

# Get transaction by ID
monarch-money tx get <transaction_id>

# Update category
monarch-money tx update <id> --category <category_id>

# Update merchant name
monarch-money tx update <id> --merchant "New Name"

# Add notes
monarch-money tx update <id> --notes "My notes here"
```

### Categories

```bash
# List all cat...