YNAB CLI

A command-line interface for YNAB designed for LLMs and developers. JSON output by default with built-in filtering.

Installation

Requires Bun.

bun install -g @stephendolan/ynab-cli

# Or run without installing
bunx @stephendolan/ynab-cli budgets list

Linux: requires libsecret for keychain storage

sudo apt-get install libsecret-1-dev  # Ubuntu/Debian
sudo dnf install libsecret-devel      # Fedora/RHEL
sudo pacman -S libsecret              # Arch

Without libsecret, use YNAB_API_KEY environment variable instead.

Authentication

ynab auth login    # Store token in OS keychain
ynab auth status   # Check authentication
ynab auth logout   # Remove credentials

Or set YNAB_API_KEY environment variable.

Commands

Budgets

ynab budgets list
ynab budgets view [id]
ynab budgets settings [id]
ynab budgets set-default <id>

Accounts

ynab accounts list
ynab accounts view <id>
ynab accounts transactions <id>

Categories

ynab categories list
ynab categories view <id>
ynab categories update <id> [--name <name>] [--note <note>] [--category-group-id <id>] [--goal-target <amount>]
ynab categories budget <id> --month <YYYY-MM> --amount <amount>
ynab categories transactions <id>

Transactions

# List with filters
ynab transactions list --account <id> --since <YYYY-MM-DD>
ynab transactions list --approved=false --min-amount 100
ynab transactions list --fields id,date,amount,memo

# Search
ynab transactions search --memo "coffee"
ynab transactions search --payee-name "Amazon"

# CRUD
ynab transactions view <id>
ynab transactions create --account <id> --amount <amount> --date <YYYY-MM-DD>
ynab transactions update <id> --amount <amount>
ynab transactions delete <id>
ynab transactions split <id> --splits '[{"amount": -50.00, "category_id": "xxx"}]'

Payees

ynab payees list
ynab payees view <id>
ynab payees update <id> --name <name>
ynab payees locations <id>
ynab payees transactions <id>

Months

ynab months list
ynab months view <YYYY-MM>

Scheduled Transactions

ynab scheduled list
ynab scheduled view <id>
ynab scheduled delete <id>

Raw API Access

ynab api GET /plans
ynab api POST /plans/{plan_id}/transactions --data '{"transaction": {...}}'

MCP Server

Run as an MCP server for AI agent integration:

ynab mcp

Output

All commands return JSON. Use --compact for minified output.

Amounts are in dollars (not YNAB's internal milliunits). --min-amount 100 means $100.

API Limitations

The YNAB API does not support updating accounts. Use the web or mobile app for this.

The API supports creating payees, categories, and category groups. Use raw API access for these:

ynab api POST /plans/{plan_id}/payees --data '{"payee": {"name": "Coffee Shop"}}'

Rate limit: 200 requests/hour per token. If exceeded, wait 5-10 minutes.

References

• YNAB API Documentation
• Specification

License

MIT