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

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 uses a layered configuration system (similar to Git, kubectl, Docker):

Config File → Environment Variables → CLI Flags (lowest precedence) (highest precedence)

Each layer overrides the previous, giving you flexible control over defaults and per-command behavior.

Config File

Create ~/.config/monarch-cli/config.toml to set persistent defaults:

# Output format: plain, json, table, csv, compact format = "plain" # Enable colored output (respects NO_COLOR env var) color = true # Show operational progress messages verbose = false # API request timeout in seconds timeout = 30 # Number of retry attempts for transient failures max_retries = 3

Environment Variables

Environment variables override config file values:

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`, `json`, `table`, `csv`, `compact`)	`plain`
`MONARCH_VERBOSE`	Enable verbose output (`1`, `true`, `yes`)	`false`
`MONARCH_DEBUG`	Enable debug mode with stack traces	`false`
`MONARCH_QUIET`	Output only IDs, one per line	`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 (no-color.org)	-

CLI Flags

CLI flags override both config file and environment variables:

# Override format for this command monarch accounts list --json # Override timeout for slow connections  monarch transactions list --timeout 60 # Disable color for this command monarch accounts list --no-color # Enable verbose output monarch accounts list --verbose

Authentication Priority

Session credentials are resolved in this order:

MONARCH_TOKEN environment variable
System keyring (if available)
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:

Create GitHub Release (tags, changelog, artifacts):

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

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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run make verify to ensure all checks pass
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Name		Name	Last commit message	Last commit date
Latest commit History 137 Commits
.github		.github
.ralph		.ralph
.tickets		.tickets
docs		docs
plans		plans
scripts		scripts
src/monarch_cli		src/monarch_cli
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
renovate.json		renovate.json
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Monarch CLI

Features

Installation

With pip

With uv (recommended)

With pipx

Verify installation

Quick Start

1. Authenticate

2. List your accounts

3. View transactions

4. Check your budget

Command Reference

Global Options

auth

accounts

transactions

budgets

cashflow

categories

Output Formats

Configuration

Config File

Environment Variables

CLI Flags

Authentication Priority

Scripting & Automation

Example: Python Integration

Stable Schema Fields

Shell Completions

Bash

Zsh

Fish

Verify

Troubleshooting

Authentication Issues

Common Issues

Debug Mode

Development

Setup

Testing

Pre-commit hooks

Releasing

Contributing

License

Acknowledgments

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages