monarch-cli 0.1.0

CLI wrapper around monarchmoneycommunity for AI agent integration with Monarch Money

Monarch CLI

A command-line interface for Monarch Money, a personal finance platform that helps you track spending, manage budgets, and monitor your net worth across all your accounts in one place.

Disclaimer: This is an unofficial, community-maintained project and is not affiliated with, endorsed by, or connected to Monarch Money in any way.

Features

• 🔐 Secure authentication with session persistence (keyring or file storage)
• 📊 Multiple output formats (plain, JSON, table, CSV, NDJSON) for flexible processing
• 🔧 Scriptable - structured JSON output auto-detected when piped
• 📅 Smart date presets (--preset this-month, --preset ytd)
• ✏️ Transaction updates with dry-run preview support
• 🔄 Account refresh to sync latest data from institutions

Installation

With pip

pip install monarch-cli

With uv (recommended)

uv tool install monarch-cli

With pipx

pipx install monarch-cli

Verify installation

monarch --version

Quick Start

1. Authenticate

# Interactive login (prompts for email/password)
monarch auth login

# Check authentication status
monarch auth status

2. List your accounts

# Human-readable format
monarch accounts list

# JSON format for scripting
monarch accounts list --json

3. View transactions

# Recent transactions
monarch transactions list

# This month's transactions
monarch transactions list --preset this-month

# Search for specific transactions
monarch transactions list --search "coffee" --limit 20

4. Check your budget

# Current budget status
monarch budgets list

# As JSON for processing
monarch budgets list --json

Command Reference

Global Options

Option	Short	Description
--version	-v	Show version and exit
--verbose	-V	Show operational progress messages
--debug		Show stack traces on errors
--json		Output in JSON format
--quiet	-q	Output only IDs, one per line
--no-color		Disable colored output
--help		Show help and exit

auth

Authentication management commands.

monarch auth login               # Interactive login
monarch auth login -s keyring    # Use system keyring storage
monarch auth login -s file       # Use file-based storage

monarch auth status              # Check authentication status
monarch auth logout              # Log out and clear credentials
monarch auth ping                # Test API connectivity
monarch auth doctor              # Diagnose authentication setup
monarch auth setup               # Show setup instructions

accounts

monarch accounts list            # List all linked accounts
monarch accounts list --json     # JSON format
monarch accounts list --format table  # Table format
monarch accounts list --raw      # Raw API response

monarch accounts refresh         # Refresh all account data
monarch accounts refresh ACC123  # Refresh specific account

transactions

# List with filters
monarch transactions list
monarch transactions list --limit 50 --offset 0
monarch transactions list --preset this-month
monarch transactions list --start 2024-01-01 --end 2024-01-31
monarch transactions list --account ACC123
monarch transactions list --search "grocery"

# Update a transaction
monarch transactions update TXN123 --amount 25.50
monarch transactions update TXN123 --description "Coffee Shop"
monarch transactions update TXN123 --category CAT456
monarch transactions update TXN123 --notes "Business expense"
monarch transactions update TXN123 --date 2024-01-15
monarch transactions update TXN123 --dry-run --amount 30.00  # Preview

# Batch update multiple transactions
monarch transactions batch-update TXN1 TXN2 TXN3 --category CAT456

Date Presets:

• today, yesterday
• this-week, last-week
• this-month, last-month
• last-30-days, last-90-days
• this-year, last-year, ytd
• all

budgets

monarch budgets list             # Budget status with spent/remaining
monarch budgets list --json      # JSON format
monarch budgets list --format table

cashflow

monarch cashflow summary                      # Current period
monarch cashflow summary --preset this-month  # This month
monarch cashflow summary --preset ytd         # Year to date
monarch cashflow summary -s 2024-01-01 -e 2024-12-31  # Date range

categories

monarch categories list          # All transaction categories
monarch categories list --json   # JSON format

Output Formats

Monarch CLI supports multiple output formats for different use cases:

Format	Description	Best For
plain	Human-readable text	Terminal display
json	Pretty-printed JSON	Scripts, parsing
table	Rich table format	Terminal display
csv	Comma-separated values	Spreadsheets
compact	Minimal JSON	Compact storage
ndjson	Newline-delimited JSON	Stream processing

# Explicit format selection
monarch accounts list --format json
monarch accounts list --format table
monarch accounts list --format csv

# Shorthand for JSON
monarch accounts list --json

# Auto-detection: JSON when piped
monarch accounts list | jq '.[0]'

Configuration

Monarch CLI can be configured via environment variables:

Variable	Description	Default
MONARCH_TOKEN	Session token for authentication	-
MONARCH_CONFIG_DIR	Directory for config files	~/.config/monarch-cli
MONARCH_SESSION_PATH	Path to session file	<config_dir>/session.json
MONARCH_FORMAT	Default output format	plain
MONARCH_VERBOSE	Enable verbose output	false
MONARCH_TIMEOUT	API timeout in seconds	30
MONARCH_MAX_RETRIES	Max API retry attempts	3
MONARCH_NO_COLOR	Disable colored output	false
NO_COLOR	Standard color disable	-

Authentication Priority

Session credentials are resolved in this order:

1. MONARCH_TOKEN environment variable
2. System keyring (if available)
3. Session file (~/.config/monarch-cli/session.json)

Scripting & Automation

Monarch CLI is designed for scripting and automation. When output is piped (non-TTY), it automatically outputs JSON:

# Auto-JSON when piped
ACCOUNTS=$(monarch accounts list | jq '.')

# Explicit JSON mode
monarch transactions list --json --preset this-month

# Quiet mode for IDs only
monarch accounts list --quiet
# Output:
# ACC123456
# ACC789012

Example: Python Integration

import subprocess
import json

def get_transactions(preset="this-month"):
    result = subprocess.run(
        ["monarch", "transactions", "list", "--preset", preset, "--json"],
        capture_output=True, text=True
    )
    return json.loads(result.stdout)

def categorize_transaction(transaction_id, category_id):
    subprocess.run([
        "monarch", "transactions", "update",
        transaction_id, "--category", category_id
    ])

# Get this month's transactions for analysis
transactions = get_transactions("this-month")
print(f"Found {len(transactions)} transactions")

Stable Schema Fields

These output fields are guaranteed stable across versions:

Accounts: id, name, balance, type, is_active, institution, last_synced

Transactions: id, date, amount, description, category, account_id, is_pending, notes

Shell Completions

Enable tab completion for commands, options, and arguments:

Bash

monarch --install-completion bash
source ~/.bashrc

Zsh

monarch --install-completion zsh
source ~/.zshrc

Fish

monarch --install-completion fish
source ~/.config/fish/completions/monarch.fish

Verify

monarch <TAB>
# Shows: accounts  auth  budgets  cashflow  categories  transactions

Troubleshooting

Authentication Issues

Run the diagnostic command to identify problems:

monarch auth doctor

This checks:

• Session file existence and permissions
• Token validity
• API connectivity
• Keyring availability

Common Issues

"Not authenticated" error:

# Re-authenticate
monarch auth login

# Or check status first
monarch auth status

Connection timeout:

# Increase timeout
MONARCH_TIMEOUT=60 monarch accounts list

# Or check connectivity
monarch auth ping

Keyring not available (headless systems):

# Use file storage instead
monarch auth login -s file

Debug Mode

For detailed error information:

monarch --debug accounts list

Development

Setup

git clone https://github.com/crcatala/monarch-cli.git
cd monarch-cli

# Install with dev dependencies
make setup
# Or manually:
uv sync --all-extras

Testing

make test          # Run tests
make test-cov      # Tests with coverage
make lint          # Lint and type check
make verify        # All checks (pre-commit)

Pre-commit hooks

Git hooks are managed with prek:

uv run prek install  # Install hooks

Releasing

Releases are a two-step process:

1. Create GitHub Release (tags, changelog, artifacts):

   make release-dry  # Preview first
   make release      # Create release
   

2. Publish to PyPI (separate step):

   uv run twine upload dist/*
   

See docs/RELEASING.md for full instructions including TestPyPI setup and troubleshooting.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run make verify to ensure all checks pass
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

MIT License - see LICENSE for details.

Acknowledgments

• monarchmoney - The community Python library for Monarch Money API
• Typer - CLI framework
• Rich - Terminal formatting