ynab-cli

A command-line interface for YNAB (You Need A Budget), built in TypeScript on top of the YNAB API.

View budgets, accounts, categories, payees and transactions — and add new transactions — without leaving your terminal.

Requirements

• Node.js 18 or newer (uses the built-in fetch)
• A YNAB account and a personal access token

Install

From npm

npm install -g @jeremyphilemon/ynab-cli
# or: pnpm add -g @jeremyphilemon/ynab-cli

This puts the ynab command on your PATH:

ynab --help

From source

pnpm install
pnpm build

This produces dist/index.js. You can then run it directly:

node dist/index.js --help

To put the ynab command on your PATH, link the package globally:

pnpm link --global      # run from this directory
ynab --help

(pnpm link --global needs pnpm setup to have been run once so the pnpm global bin directory is on your PATH. Undo later with pnpm uninstall --global ynab-cli.)

During development you can skip the build step and run the TypeScript directly via tsx:

pnpm dev --help
pnpm dev accounts
pnpm dev transactions --account Checking --limit 10

Note: with pnpm, pass command arguments straight to pnpm dev — do not use a -- separator. pnpm 10 forwards extra args automatically and would otherwise pass the literal -- through to the CLI.

Authentication

Create a personal access token at https://app.ynab.com/settings/developer, then save it:

ynab login

The token is verified against the API and stored at ~/.config/ynab-cli/config.json (mode 600).

A token is resolved from, in order of precedence:

1. the --token <token> flag
2. the YNAB_TOKEN environment variable
3. the saved config file (ynab login)

Usage

ynab [global options] <command> [command options]

Global options:
  -b, --budget <id>   budget to operate on (defaults to the saved budget,
                      otherwise YNAB's "last-used" budget)
  --token <token>     access token for this invocation
  --json              print raw JSON instead of formatted tables
  -v, --version       print the version
  -h, --help          show help (works on any subcommand)

Commands

| Command | Description | | --- | --- | | ynab login | Save and verify your access token | | ynab logout | Remove the stored token | | ynab config | Show config; config set-budget <id>, config path | | ynab user | Show the authenticated user | | ynab budgets | List budgets; budgets use <id> sets the default | | ynab accounts | List accounts and balances (--all includes closed) | | ynab categories | List category groups (--all includes hidden) | | ynab payees | List payees (--transfers includes transfer payees) | | ynab months | List budget months (--limit <n>) | | ynab month [month] | Show one month's detail (default: current) | | ynab transactions | List transactions (alias: txns) | | ynab add | Add a transaction | | ynab update <id> | Update a transaction — approve, recategorize, etc. (alias: edit) |

Examples

# Pick a default budget so you don't repeat --budget
ynab budgets
ynab budgets use 1a2b3c4d-....

# Inspect a budget
ynab accounts
ynab categories --all
ynab month current

# List transactions, filtered
ynab transactions --limit 10
ynab transactions --account Checking --since 2026-05-01
ynab transactions --category "Dining Out" --json

# Add a $4.50 coffee outflow from Checking
ynab add --account Checking --amount -4.50 \
         --payee "Blue Bottle" --category "Dining Out" --memo "latte"

# Add income, cleared, on a specific date
ynab add -A Savings -m 1500 -p "Paycheck" -d 2026-05-15 -c cleared

# Update an existing transaction (only the fields you pass change)
ynab update 1a2b3c4d-.... --approve
ynab update 1a2b3c4d-.... --category "Groceries" --memo "weekly shop"

Every option of ynab update is optional — unspecified fields keep their current values. Approving an imported transaction is just ynab update <id> --approve. Split transactions can't be updated from the CLI; edit those in the YNAB app.

--account and --category accept either a YNAB id or a name (a unique case-insensitive substring match is enough).

Notes on amounts

YNAB stores money as milliunits (1000 milliunits = one currency unit). This CLI does the conversion for you: pass ordinary decimal amounts to ynab add (e.g. -12.50). Negative amounts are outflows; positive are inflows. Displayed balances are formatted with the budget's own currency settings.

Project layout

src/
  index.ts            CLI entry point, command wiring, error handling
  context.ts          token / budget resolution, shared helpers
  config.ts           config file load/save (~/.config/ynab-cli)
  api/
    client.ts         fetch-based YNAB API client
    types.ts          YNAB API type definitions
  commands/           one file per command group
  util/
    format.ts         colors, currency math, table rendering
    prompt.ts         interactive (hidden) prompts

Rate limits

The YNAB API permits 200 requests per hour per token. Each command makes only a few requests; ynab user prints the remaining quota.

License

MIT