https://github.com/stephendolan/ynab-cli
Command-line interface for YNAB (You Need a Budget) - JSON output optimized for LLMs and developers
https://github.com/stephendolan/ynab-cli
Last synced: 3 months ago
JSON representation
Command-line interface for YNAB (You Need a Budget) - JSON output optimized for LLMs and developers
- Host: GitHub
- URL: https://github.com/stephendolan/ynab-cli
- Owner: stephendolan
- License: mit
- Created: 2025-10-28T15:24:19.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-03-04T03:49:21.000Z (4 months ago)
- Last Synced: 2026-03-04T08:21:48.084Z (4 months ago)
- Language: TypeScript
- Size: 243 KB
- Stars: 9
- Watchers: 0
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# YNAB CLI
[](https://www.npmjs.com/package/@stephendolan/ynab-cli)
[](https://opensource.org/licenses/MIT)
A command-line interface for YNAB designed for LLMs and developers. JSON output by default with built-in filtering.
## Installation
Requires [Bun](https://bun.sh).
```bash
bun install -g @stephendolan/ynab-cli
# Or run without installing
bunx @stephendolan/ynab-cli budgets list
```
Linux: requires libsecret for keychain storage
```bash
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
```bash
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
```bash
ynab budgets list
ynab budgets view [id]
ynab budgets settings [id]
ynab budgets set-default
```
### Accounts
```bash
ynab accounts list
ynab accounts view
ynab accounts transactions
```
### Categories
```bash
ynab categories list
ynab categories view
ynab categories update [--name ] [--note ] [--category-group-id ] [--goal-target ]
ynab categories budget --month --amount
ynab categories transactions
```
### Transactions
```bash
# List with filters
ynab transactions list --account --since
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
ynab transactions create --account --amount --date
ynab transactions update --amount
ynab transactions delete
ynab transactions split --splits '[{"amount": -50.00, "category_id": "xxx"}]'
```
### Payees
```bash
ynab payees list
ynab payees view
ynab payees update --name
ynab payees locations
ynab payees transactions
```
### Months
```bash
ynab months list
ynab months view
```
### Scheduled Transactions
```bash
ynab scheduled list
ynab scheduled view
ynab scheduled delete
```
### Raw API Access
```bash
ynab api GET /budgets
ynab api POST /budgets/{budget_id}/transactions --data '{"transaction": {...}}'
```
### MCP Server
Run as an MCP server for AI agent integration:
```bash
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 creating categories, category groups, or payees. Use the web or mobile app for these.
Rate limit: 200 requests/hour per token. If exceeded, wait 5-10 minutes.
## References
- [YNAB API Documentation](https://api.ynab.com/)
- [Specification](./SPEC.md)
## License
MIT