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 categories monarch-money cat list # List with IDs (for updates) monarch-money cat list --show-ids ``` ### Accounts ```bash # List accounts monarch-money acc list # Show account details monarch-money acc get <account_id> ``` ### Doctor (Diagnostics) ```bash # Run diagnostic checks monarch-money doctor ``` Checks: - Environment variables set - API connectivity - Session validity - Node.js version ## Library Usage Import and use the TypeScript library directly: ```typescript import { MonarchClient } from 'monarch-money'; const client = new MonarchClient({ baseURL: 'https://api.monarch.com' }); // Login await client.login({ email: process.env.MONARCH_EMAIL, password: process.env.MONARCH_PASSWORD, mfaSecretKey: process.env.MONARCH_MFA_SECRET }); // Get transactions const transactions = await client.transactions.getTransactions({ limit: 10 }); // Get categories const categories = await client.categories.getCategories(); // Get accounts const accounts = await client.accounts.getAll(); ``` ## Common Workflows ### Find and Update a Transaction ```bash # 1. Find the transaction monarch-money tx list --date 2026-01-15 --merchant "Target" # 2. Get category ID monarch-money cat list --show-ids # 3. Update the transaction monarch-money tx update <transaction_id> --category <category_id> ``` ### Search Transactions by Date Range ```bash monarch-money tx list --start-date 2026-01-01 --end-date 2026-01-31 --limit 100 ``` ### Check Budget Status ```bash monarch-money acc list ``` ## Error Handling | Error | Solution | |-------|----------| | "Not logged in" | Run `monarch-money auth login` | | "MFA code required" | Set `MONARCH_MFA_SECRET` environment variable | | "Invalid credentials" | Verify email/password work at app.monarchmoney.com | | "Session expired" | Run `monarch-money auth login` again | ## Session Management Sessions are cached locally at `~/.mm/session.json`. After initial login, subsequent commands reuse the saved session for faster execution. To clear the session: `monarch-money auth logout` ## References - [API.md](references/API.md) - GraphQL API details and advanced usage - [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) - Common issues and solutions