# managing-monarch-money

> Manages Monarch Money transactions, categories, accounts, and receipt splits. Use when the user needs Monarch Money budgeting or transaction operations.

- Author: Octo
- Repository: davideasaf/managing-monarch-money
- Version: 20260125141419
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/davideasaf/managing-monarch-money
- Web: https://mule.run/skillshub/@@davideasaf/managing-monarch-money~managing-monarch-money:20260125141419

---

---
name: managing-monarch-money
description: Manages Monarch Money transactions, categories, accounts, and receipt splits. Use when the user needs Monarch Money budgeting or transaction operations.
metadata:
  clawdbot:
    emoji: "💰"
---

# Monarch Money CLI Skill

Use this skill when the user needs to interact with Monarch Money for budgeting tasks.

## Quick start

```bash
cd ~/clawd/managing-monarch-money
npm install && npm run link
managing-monarch-money auth login -e <email> -p <password>
```

## When to use

- Search or list transactions
- Update transaction categories or notes
- Split a receipt across multiple categories
- List budget categories
- View account balances
- Categorize multiple transactions

## Requirements

- Node.js 18+
- `monarchmoney` npm package
- Session stored at `~/.mm/session.json`
- API endpoint: `https://api.monarch.com`
- Optional MFA secret: `MONARCH_MFA_SECRET`

## Common commands

### Search transactions
```bash
# By merchant
managing-monarch-money tx search -m "Amazon" --json

# By date range
managing-monarch-money tx search --start YYYY-MM-DD --end YYYY-MM-DD

# By category
managing-monarch-money tx search -c "Groceries" -l 50
```

### Update transactions
```bash
# Set category
managing-monarch-money tx categorize <transactionId> <categoryId>

# Add notes
managing-monarch-money tx update <transactionId> -n "Weekly shopping"
```

### List categories
```bash
# All categories (use to find category IDs)
managing-monarch-money cat list --json

# Search by name
managing-monarch-money cat search "subscription"
```

### Split receipts
```bash
# Create split file from receipt analysis
echo '[
  {"description": "Groceries", "amount": 45.99, "category": "Groceries"},
  {"description": "Household", "amount": 12.50, "category": "Home"}
]' > /tmp/split.json

# Preview split
managing-monarch-money receipts split <transactionId> -f /tmp/split.json --dry-run

# Apply split
managing-monarch-money receipts split <transactionId> -f /tmp/split.json
```

### View accounts
```bash
managing-monarch-money acc list --json
```

### Diagnostics
```bash
# Check environment, session, and API connectivity
managing-monarch-money doctor
```

## Workflow: receipt processing

1. **Analyze the receipt** (extract line items + amounts)
2. **Find the transaction**
   ```bash
   managing-monarch-money tx search -m "<merchant>" --start YYYY-MM-DD --json
   ```
3. **Get category IDs**
   ```bash
   managing-monarch-money cat search "<category name>" --json
   ```
4. **Create split items JSON**
5. **Apply the split**
   ```bash
   managing-monarch-money receipts split <transactionId> -f /tmp/split.json
   ```

## Workflow: bulk categorization

1. **Search for uncategorized**
   ```bash
   managing-monarch-money tx search -c "Uncategorized" --json
   ```
2. **Find target category**
   ```bash
   managing-monarch-money cat search "<name>" --json
   ```
3. **Update each transaction**
   ```bash
   managing-monarch-money tx categorize <id1> <categoryId>
   managing-monarch-money tx categorize <id2> <categoryId>
   ```

## JSON output

Always use `--json` when parsing results programmatically:

```bash
# Get transaction IDs
managing-monarch-money tx search -m "Amazon" --json | jq '.[].id'

# Get category ID by name
managing-monarch-money cat list --json | jq '.[] | select(.name == "Groceries") | .id'
```

## Error handling

- **Not logged in:** `managing-monarch-money auth login`
- **Session expired:** `managing-monarch-money auth login`
- **Category not found:** `managing-monarch-money cat search "<name>"`

## Tips

- Use aliases: `tx`, `cat`, `acc`
- Use `--json` for scripting, tables for human review
- Use `--dry-run` before receipt splits

## Integration tests

Run the weekly smoke suite:

```bash
cd ~/clawd/managing-monarch-money
npm run e2e
```

Optional write test (updates notes then reverts):

```bash
WRITE_TEST=1 npm run e2e
```