ynab-export

command module
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 7, 2026 License: MIT Imports: 17 Imported by: 0

README

YNAB Export Tool

A simple, beginner-friendly tool to export your YNAB (You Need A Budget) budget data for import into Actual Budget.

This tool simplifies the export process described in the Actual Budget migration guide by providing an interactive terminal interface that guides you through each step.

Quick Start

  1. Download the binary for your platform
  2. Get your YNAB API token from Developer Settings
  3. Run the tool from your terminal
  4. Follow the prompts to select and export your budget
  5. Import into Actual Budget using the exported file

🔒 Secure • 🚀 Fast • 🌐 Cross-platform • 📦 No installation required

Installation

Download Pre-built Binary

Download the latest release for your operating system from the Releases page.

Choose the appropriate binary:

  • Windows: ynab-export_*_windows_amd64.exe
  • macOS (Intel): ynab-export_*_darwin_amd64
  • macOS (Apple Silicon): ynab-export_*_darwin_arm64
  • Linux (64-bit): ynab-export_*_linux_amd64
  • Linux (ARM64): ynab-export_*_linux_arm64

The binaries are ready to run - no extraction or installation needed!

Advanced: Build from Source
Build from Source

If you have Go installed (version 1.25 or later), you can build from source:

Note: This project uses Go's experimental encoding/json/v2 package. You'll need to set the GOEXPERIMENT environment variable.

GOEXPERIMENT=jsonv2 go install github.com/StephenBrown2/ynab-export@latest

Or clone and build:

git clone https://github.com/StephenBrown2/ynab-export.git
cd ynab-export
GOEXPERIMENT=jsonv2 go build
Using Just (Build Tool)

If you have Just installed:

# Build for current platform
just build

# Build for all platforms
just build-all

# Run directly
just run

# See all available commands
just

Usage

Step 1: Get Your YNAB API Token

Before running the tool, you'll need a YNAB Personal Access Token:

  1. Sign in to the YNAB web app
  2. Go to Account Settings → Developer Settings
  3. Under "Personal Access Tokens", click New Token
  4. Enter your password and click Generate
  5. Important: Copy the FULL token from the top of the page (under "New Personal Access Token:")
    • Do NOT use the partially obfuscated token shown in the table (e.g., XXXXXXXXXX-Wax0q8)
    • The token is only shown once, so copy it immediately!

Direct link: YNAB Developer Settings

Step 2: Run the Tool

Simply run the downloaded binary:

Linux/macOS:

# Make it executable (first time only)
chmod +x ynab-export_*_linux_amd64  # or darwin_amd64/darwin_arm64

# Run it
./ynab-export_*_linux_amd64

Windows:

Run from Command Prompt, PowerShell, or Windows Terminal:

ynab-export_0.0.1_windows_amd64.exe

Note: Do not double-click the .exe file - it must be run from a terminal to interact with the application properly.

Recommended: Install Windows Terminal for the best experience. It's free from the Microsoft Store and provides a modern terminal with better colors and font rendering.

To install: Open Microsoft Store → Search "Windows Terminal" → Click "Get"

Once installed, right-click in your Downloads folder and select "Open in Terminal" to run the executable.

Tip: You can rename the binary to simply ynab-export (or ynab-export.exe on Windows) for easier use.

Step 3: Follow the Prompts

The tool will guide you through:

  1. Enter your API token (the token you generated in Step 1)
    • Tip: Set the YNAB_API_TOKEN environment variable to skip entering your token each time
  2. Select your budget from the list of budgets in your YNAB account
  3. Wait for export - the tool downloads your budget data
  4. Done! Your budget is saved to ~/Downloads/ynab-export-budget-name-YYYYMMDD-HHMMSS.json
Advanced: Using Environment Variable for Token

To skip entering your token each time, set the YNAB_API_TOKEN environment variable:

# Linux/macOS
export YNAB_API_TOKEN="your-token-here"
./ynab-export

# Windows (PowerShell)
$env:YNAB_API_TOKEN="your-token-here"
.\ynab-export.exe

# Windows (Command Prompt)
set YNAB_API_TOKEN=your-token-here
ynab-export.exe

The tool will automatically validate the token from the environment variable and skip the token entry screen if valid.

Step 4: Import into Actual Budget

Now that you have your exported JSON file:

  1. Open Actual Budget
  2. Select the dropdown menu and choose Close File
  3. Click Import file
  4. Select nYnab as the import type
  5. Choose the exported JSON file from your Downloads folder
  6. Follow any cleanup steps mentioned in the Actual Budget migration guide

Screenshots

1. Welcome Screen (Token Entry)
┌────────────────────────────────────────────────────┐
│ YNAB Budget Exporter                               │
│                                                    │
│ This tool will help you export your YNAB budget   │
│ for import into Actual Budget.                    │
│                                                    │
│ To get your API token:                            │
│   1. Sign in to the YNAB web app                  │
│   2. Go to Account Settings → Developer Settings  │
│   3. Under 'Personal Access Tokens', click 'New'  │
│   4. Enter your password and click 'Generate'     │
│                                                    │
│ Enter your YNAB API token: ••••••••••••••••••••   │
│                                                    │
│ Press Enter to continue • Ctrl+C to quit          │
└────────────────────────────────────────────────────┘
2. Token Validation
┌────────────────────────────────────────────────────┐
│ YNAB Budget Exporter                               │
│                                                    │
│ ✓ Token validated successfully                     │
│                                                    │
│ Fetching your budgets...                          │
└────────────────────────────────────────────────────┘
3. Budget Selection
┌────────────────────────────────────────────────────┐
│ YNAB Budget Exporter                               │
│                                                    │
│ Select a budget to export:                        │
│                                                    │
│ > Personal Budget (Last Modified: 2025-10-14)     │
│   f1a2b3c4-d5e6-7f8g-9h0i-1j2k3l4m5n6o             │
│                                                    │
│   Family Budget (Last Modified: 2025-10-10)       │
│   a1b2c3d4-e5f6-7g8h-9i0j-1k2l3m4n5o6p             │
│                                                    │
│   Business Budget (Last Modified: 2025-09-28)     │
│   z9y8x7w6-v5u4-t3s2-r1q0-p9o8n7m6l5k4             │
│                                                    │
│ Use ↑/↓ to navigate • / to search • Enter to      │
│ select • Esc to go back • q/Ctrl+C to quit        │
└────────────────────────────────────────────────────┘
4. Export in Progress
┌────────────────────────────────────────────────────┐
│ YNAB Budget Exporter                               │
│                                                    │
│ Exporting Budget...                               │
│                                                    │
│ Downloading budget: Personal Budget               │
│ Please wait...                                    │
└────────────────────────────────────────────────────┘
5. Export Complete with Budget Summary
┌────────────────────────────────────────────────────┐
│ ✓ Export Complete!                                │
│                                                    │
│ Budget: Personal Budget                           │
│ Saved to: ~/Downloads/ynab-export-personal-       │
│           budget-20251015-143022.json             │
│                                                    │
│ Budget Summary:                                   │
│   Currency:     USD ($)                           │
│   Accounts:     8 (plus 2 closed)                 │
│   Categories:   24 (plus 3 hidden, 1 deleted)     │
│   Payees:       142                               │
│   Transactions: 1,847                             │
│   Date Range:   Jan 2023 to Oct 2025              │
│   File Size:    2.3 MB                            │
│                                                    │
│ You can now import this file into Actual Budget:  │
│   1. Open Actual Budget                           │
│   2. If a budget is already open, select the      │
│      dropdown menu and 'Close File'               │
│   3. Select 'Import file'                         │
│   4. Choose 'nYNAB'                               │
│   5. Select the exported JSON file                │
│   6. Once imported, review your budget and        │
│      follow cleanup steps at                      │
│      actualbudget.org/docs/migration/nynab#cleanup│
│                                                    │
│ Press Enter or q to quit                          │
└────────────────────────────────────────────────────┘

Keyboard Shortcuts

  • Arrow Keys (↑/↓): Navigate through budget list
  • / : Filter/search budgets
  • Enter: Select/Confirm
  • Esc: Go back to previous screen
  • Ctrl+C or q: Quit the application

Troubleshooting

"API error: 401 Unauthorized"

Your API token is invalid or expired. Generate a new token from YNAB's Developer Settings.

"No budgets found"

Make sure you have at least one budget in your YNAB account.

"Permission denied" when saving file

Check that you have write permissions to your Downloads folder.

Binary won't run on macOS

macOS may block the binary because it's not from an identified developer. To run it:

# Replace with your actual binary name, e.g., ynab-export_0.0.1_darwin_arm64
xattr -d com.apple.quarantine ynab-export_*_darwin_*

# Or make it executable
chmod +x ynab-export_*_darwin_*

Or right-click the file, select "Open", and click "Open" in the security dialog.

Contributing

We welcome contributions! Please see CONTRIBUTING.md

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • YNAB for their excellent budgeting software and API
  • Actual Budget for the open-source alternative
  • Charm Bracelet for the beautiful TUI libraries (Bubble Tea)

Support

If you encounter any issues or have questions:

  1. Check the Troubleshooting section above
  2. Review the Issues page
  3. Create a new issue if your problem isn't already listed

Note: This tool is not affiliated with YNAB or Actual Budget. It's a community project to help users migrate their data.

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.