ynab-cockpit

README

YNAB Cockpit

A local-first reporting cockpit for YNAB, plus complete access to all 44 operations in the public API. It is designed for humans, scripts, and local AI agents that need structured financial data without an intermediate service.

Reports are read-only. API mutations remain available for complete coverage but are blocked by default and require --allow-write on every invocation.

Unofficial. This project is not affiliated with or endorsed by YNAB.

Install

Requires Go 1.22 or newer:

go install github.com/santanaluiz/ynab-cockpit/cmd/ynab@latest
ynab --version

Configure

ynab config init

This prompts for the token without echoing it and writes ~/.config/ynab/config.yaml with permissions 0600. Create a personal access token at https://app.ynab.com/settings/developer. plan_id: last-used selects the most recently opened plan.

The environment variables YNAB_ACCESS_TOKEN, YNAB_PLAN_ID, YNAB_BASE_URL, and YNAB_CONFIG are also supported. The token is deliberately unavailable as a CLI flag because command lines commonly leak into shell history and process lists.

Reports

Report amounts use normal currency units rather than YNAB milliunits. Output is stable JSON suitable for jq, scripts, or a local agent.

# Monthly executive summary
ynab report briefing --month 2026-07

# Spending rankings and trends
ynab report spending --since 2026-01-01 --until 2026-07-31 --group-by category
ynab report spending --since 2026-01-01 --until 2026-07-31 --group-by payee
ynab report spending --since 2026-01-01 --until 2026-07-31 --group-by month

# Likely recurring monthly charges
ynab report subscriptions --since 2025-08-01

# Current account composition and net worth
ynab report net-worth

The monthly briefing includes income, spending, saved amount, savings rate, month-over-month change, top categories and payees, and largest outflows. Transfers are excluded and split transactions are attributed to their actual subcategories.

Complete API access

# Explore all operations
ynab schema --list
ynab accounts list
ynab transactions list --since-date 2026-01-01

# Preview a mutation; this makes no request
ynab transactions create --dry-run --json '{
  "transaction": {
    "account_id": "abc-123",
    "date": "2026-07-31",
    "amount": -42500,
    "payee_name": "Corner Store",
    "memo": "Groceries"
  }
}'

# A real mutation requires an explicit unlock
ynab transactions create --allow-write --json '{...}'

Raw API amounts are milliunits: $10.00 = 10000, -$42.50 = -42500.

Security

• No telemetry or intermediate backend.
• HTTPS is mandatory except for localhost test servers.
• Token input is hidden, storage is 0600, and unmasked token output is absent.
• Mutations fail closed unless --allow-write is supplied.
• CI uses read-only permissions and pinned release-action commits.

See SECURITY.md for the threat model and reporting process.

Upstream and license

YNAB Cockpit is a security-hardened fork of glebmish/ynab-cli. The upstream project provides the excellent full-API command foundation; this fork adds reporting, read-only defaults, and a tighter local credential model.

MIT © Gleb Mishchenko and contributors.

YNAB and You Need A Budget are trademarks of their respective owners.