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:

•Login to https://app.monarchmoney.com
•Go to Settings > Security > Two-Factor Authentication
•If MFA is already enabled: disable and re-enable to get a new secret
•When shown the QR code: click "Can't scan? View setup key"
•Copy the secret key (base32 string like JBSWY3DPEHPK3PXP)
•Complete MFA setup in Monarch Money with an authenticator app
•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"

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

Automation Workflows

Weekly Reconciliation (Cron: Sunday 9am)

Automatically reviews recent transactions and sends Telegram summary of:

•Transactions that look miscategorized
•Uncategorized transactions needing review

Manual Review

bash

# Review last 30 days of transactions
cd skills/monarch-money && node dist/cli/index.js tx search --limit 50

# Search for specific merchant
node dist/cli/index.js tx search --merchant "Amazon" --limit 20

# List categories with IDs
node dist/cli/index.js cat list

Re-categorize Transactions

bash

# Find category ID
node dist/cli/index.js cat search "Gas"

# Apply category to transaction
node dist/cli/index.js tx categorize <transaction_id> <category_id>

# Update merchant name
node dist/cli/index.js tx update <id> --merchant "Corrected Name"

# Add notes
node dist/cli/index.js tx update <id> --notes "Business expense - Client X"

Auto-Categorization Rules

Edit references/categorization-rules.json to add merchant patterns:

json

{
  "gas": {
    "category": "Gas",
    "patterns": ["sheetz", "shell", "exxon"]
  }
}

References

•API.md - GraphQL API details and advanced usage
•TROUBLESHOOTING.md - Common issues and solutions
•categorization-rules.json - Auto-categorization patterns