Skip to content

A local-first personal finance app

[AI] docs(migration): expand nYNAB export with tabbed alternatives (#8155)

Stephen Brown II0ae9f91e6268
diff --git a/.github/actions/docs-spelling/expect.txt b/.github/actions/docs-spelling/expect.txt
index fe76f51c1f..7fc0d34119 100644
--- a/.github/actions/docs-spelling/expect.txt
+++ b/.github/actions/docs-spelling/expect.txt
@@ -7,6 +7,7 @@ admins
AESUDEF
ajv
ALZEY
+amd
Anglais
ANZ
aql
diff --git a/packages/docs/docs/migration/nynab.md b/packages/docs/docs/migration/nynab.md
deleted file mode 100644
index c19d34cf22..0000000000
--- a/packages/docs/docs/migration/nynab.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Migrating from nYNAB
-
-In order to export your budget from YNAB, you will need to use one of two methods.
-
-## 3rd Party nYnab Exporter
-
-This is the easiest method available. While we don't maintain this tool, https://json-exporter-for-ynab.netlify.app will handle authorizing with your account to export your nYNAB budget into JSON.
-
-## Export Using API Key
-
-If you don't want to use a third party tool, you will need an API key.
-
-### Step 1. Get API key
-
-If you don't already have an API key, you'll need to:
-
- Sign in to the YNAB web app
- Go to the "Account Settings" page, then to the "Developer Settings" page
- Under the "Personal Access Tokens" section, click "New Token"
- Enter your password and click "Generate" to get a new access token
-
-:::caution
-The API key is only shown once, so make sure you copy it down somewhere! More information on how to access the YNAB API can be found at https://api.youneedabudget.com/
-:::
-
-### Step 2. Get budget ID
-
-Now open a terminal window / command prompt, and enter:
-
-```
-curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.youneedabudget.com/v1/budgets
-```
-
-This will get the list of all the budgets you have. You'll need to find the id of the budget you want to export.
-
-:::note
-
-It might help to use pretty formatting to find the budget id by piping to `jq` (which can be installed with homebrew `brew install jq`):
-
-```
-curl -sH "Authorization: Bearer <ACCESS_TOKEN>" https://api.youneedabudget.com/v1/budgets | jq -r '.data.budgets | sort_by(.last_modified_on) | reverse | .[] | "\(.name): \(.id)"'
-```
-
-If you receive an error message like: `Invoke-WebRequest : Cannot bind parameter 'Headers'`, this is because curl is probably aliased to the "Invoke-WebRequest" Powershell commandlet. Use `curl.exe` instead of just `curl` in the commands below to fix this.
-
-:::
-
-### Step 3. Download entire plan
-
-Use the budget id to perform the following API request:
-
-```
-curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.youneedabudget.com/v1/budgets/<BUDGET ID> --output budget.json
-```
-
-### Import the JSON File
-
-- Open Actual
-- Select the drop down menu and **Close File**
-- Select **Import file**
-
-![](/img/migrating/actual-import-1.webp)
-
-- Select **nYnab**
-
-![](/img/migrating/actual-import-2.webp)
-
-- Choose the exported JSON file
-
-### Cleanup
-
-#### Credit Cards (Fix Overspending)
-
-If you import credit cards with previous debt, you must handle these differently. Otherwise, your budget months will show overspending. Actual does not handle carrying over debt the same way, but offers a more manual approach.
-
-1. From the Budget screen, create a category named `Credit Card` (perhaps under a Category Group of `Debt`).
-2. Change all overspent transactions to have their category be this `Credit Card` category.
-3. On the first month of overspending for this category, click on the Balance (it should show red) and select `Rollover overspending`.
-4. Next, you must assign money each historical month to cover any payments of the `Credit Card` category. Open YNAB and look through each month to find the "extra" amount assigned to the card. (To find the "extra," open YNAB and look through each month. Find the amount assigned to the card in excess of any additional monthly spending, which is how much was used to pay the debt on the credit card.) Put this amount in your `Credit Card` category in Actual.
-5. If your budget isn't zeroing out yet, follow the instructions below in _Hold For Next Month_.
-
-A full description of how to carry over debt can be found in [our Carrying Debt article.](https://actualbudget.org/docs/budgeting/credit-cards/carrying-debt)
-
-#### Hold for Next Month (Fix Money Leftover in To Budget)
-
-nYNAB calculates its `Ready to Assign` value differently than Actual's `To Budget` value.
-There is no need to worry, we can make them match exactly with a simple change.
-This is purely a visual change and doesn't affect the budget itself.
-
-You will likely see money leftover in each of the imported months in your `To Budget`.
-This extra comes from nYNAB including funds budgeted in future months when calculating its `Ready to Assign` value.
-Actual does not include those funds by default, but offers a way to manually reserve funds for use in future months.
-This is affectively the same thing nYNAB does, but in a manual form.
-To `hold` the leftover funds for the next month follow these steps:
-
-1. Click on your `To Budget` value for the month.
-2. Select `Hold for next month`.
-3. Fill in how much you would like to reserve for the future. By default the current `To Budget` value is filled in. Using this value will bring your `To Budget` to zero.
-4. Click `Hold`.
-5. Repeat for all desired months.
-
-A full description of how funds rollover and the `hold` feature can be found in [this article.](../budgeting/#how-money-rolls-over)
-
-#### Duplicate Categories or Groups
-
-Actual does not allow duplicate category groups, or duplicate categories within a group.
-This happens sometimes in YNAB especially if you have an old hidden category or group that has been forgotten about.
-Actual is automatically rename these duplicates by appending a `-1` to the end of the name (potentially higher numbers if you have multiple duplicates).
-Make sure to show hidden categories to see if you have any of these duplicates.
-To see your hidden categories select the "Toggle Hidden Categories" option in the kebab menu next to the "Categories" header.
-
-**To Fix duplicate groups**:
-
-1. Move any categories inside the duplicate group to a different group.
-2. Delete the duplicate group by selecting "Delete" in the menu next to the group name.
-
-**To Fix Duplicate Categories**:
-
-1. Find the duplicate category and select "Delete" in the menu next to the category name.
-2. Choose what category to move any transactions to that are part of this duplicate category.
diff --git a/packages/docs/docs/migration/nynab.mdx b/packages/docs/docs/migration/nynab.mdx
new file mode 100644
index 0000000000..c50cabf7f8
--- /dev/null
+++ b/packages/docs/docs/migration/nynab.mdx
@@ -0,0 +1,250 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Migrating from nYNAB
+
+To export your budget from YNAB, choose one of the methods below. **Option A** is the easiest for most users. If that tool is unavailable, **Options B, C, and D** provide alternatives.
+
+## Third-Party Web Tool
+
+This is the easiest method available. Visit [https://json-exporter-for-ynab.netlify.app](https://json-exporter-for-ynab.netlify.app), which guides you through authorizing your YNAB account and downloading your budget as a JSON file.
+
+:::note
+This tool is maintained by the community, not the Actual Budget team.
+:::
+
+Once you have the JSON file, skip ahead to [Import the JSON File](#import-the-json-file).
+
+If the json-exporter tool above does not work for any reason (it appears to be blocked by YNAB occasionally), you may try one of the following options.
+
+## Alternative Export Methods
+
+### Getting Your YNAB API Token
+
+The alternative options all require a YNAB Personal Access Token. Follow these steps once, then use the token in whichever option you choose.
+
+1. Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer), sign in if needed.
+2. Under "Personal Access Tokens", click **New Token**.
+3. Enter your password and click **Generate**.
+4. Copy the full token shown at the top of the page. Do not copy the shorter, partially hidden version shown in the table below it.
+
+![Generating a new YNAB Personal Access Token](/img/migrating/nynab-api-ui-pat-token.png)
+
+:::caution
+The token is only displayed once. Copy it to a safe place before closing the page. More information about the YNAB API can be found at [api.youneedabudget.com](https://api.youneedabudget.com/).
+:::
+
+### Options
+
+<Tabs>
+ <TabItem value="api-ui" label="API Documentation UI" default>
+
+This method uses YNAB's official API documentation website, which has a built-in interface for making API requests directly from your browser. No additional tools are required.
+
+Before you start, [get your YNAB API token](#getting-your-ynab-api-token) if you have not already.
+
+#### Step 1: Get Your Budget ID
+
+1. Open the [Get All Plans endpoint](https://api.ynab.com/v1#tag/plans/GET/plans) in your browser
+2. Click **Try it out**, then click **Execute** (or "Test Request")
+
+![The YNAB API documentation showing the Get All Plans endpoint](/img/migrating/nynab-api-ui-all-plans.webp)
+
+3. In the **Authorization** field that appears, paste your API token into the **Bearer Token** box and click **Send**
+
+![Pasting the bearer token and sending the request](/img/migrating/nynab-api-ui-bearer-token.webp)
+
+4. In the response body, find the entry for your budget and copy its `id` value (for example, `8800b4e7-937f-4cdb-a7e7-fc35b794f85b`)
+
+#### Step 2: Download Your Budget
+
+1. Open the [Get a Plan endpoint](https://api.ynab.com/v1#tag/plans/GET/plans/{plan_id}) in your browser
+2. Click **Try it out**
+
+![The Get Plan by ID endpoint in the YNAB API documentation](/img/migrating/nynab-api-ui-get-plan.webp)
+
+3. Paste your budget ID into the `plan_id` field and click **Send**
+4. Once the response appears in the Body panel on the right, click **Download** to save the JSON file
+
+![Clicking Download to save the YNAB plan JSON file](/img/migrating/nynab-api-ui-download.webp)
+
+#### Step 3: Fix the JSON File
+
+The file from this endpoint uses a slightly different format than what Actual expects. You need to make one small edit before importing.
+
+1. Open the downloaded JSON file in a plain text editor (Notepad on Windows, TextEdit on macOS)
+2. At the very start of the file, find the text `"plan"` and change it to `"budget"`
+3. Save the file
+
+![The JSON file in a text editor, showing "plan" that must be changed to "budget"](/img/migrating/nynab-api-ui-json-edit.png)
+
+:::warning
+Skipping this step causes a **not-ynab5** error when importing. Make sure the file begins with `{"data": {"budget"` before proceeding.
+:::
+
+ </TabItem>
+ <TabItem value="cli" label="CLI Tool">
+
+The [ynab-export](https://github.com/StephenBrown2/ynab-export) tool is a terminal app that walks you through the export process step by step. It works on Windows, macOS, and Linux, and requires no installation beyond downloading a single file.
+
+Before you start, [get your YNAB API token](#getting-your-ynab-api-token) if you have not already.
+
+#### Step 1: Download the Tool
+
+Go to the [Releases page](https://github.com/StephenBrown2/ynab-export/releases/latest) and download the file for your operating system:
+
+| Operating System | File to download |
+| ---------------------------------- | --------------------------------- |
+| Windows | `ynab-export_*_windows_amd64.exe` |
+| macOS (Apple Silicon / M1, M2, M3) | `ynab-export_*_darwin_arm64` |
+| macOS (Intel) | `ynab-export_*_darwin_amd64` |
+| Linux (64-bit) | `ynab-export_*_linux_amd64` |
+
+The downloaded file is ready to run. No installation or extraction is needed. You may want to rename it to `ynab-export.exe` (Windows) or `ynab-export` (macOS/Linux) for simpler usage.
+
+#### Step 2: Run the Tool
+
+**On Windows:**
+
+Open Command Prompt, PowerShell, or Windows Terminal. Navigate to the folder where you saved the file and run:
+
+```cmd
+ynab-export.exe
+```
+
+:::tip
+Do not double-click the `.exe` file. It must be run from a terminal window to work correctly.
+
+For the best experience, install [Windows Terminal](https://aka.ms/terminal) from the Microsoft Store (search "Windows Terminal" and click **Get**). Once installed, right-click in your Downloads folder and select **Open in Terminal**.
+:::
+
+**On macOS or Linux:**
+
+Open a terminal, navigate to the folder where you downloaded the file, and run:
+
+```bash
+chmod +x ynab-export
+./ynab-export
+```
+
+If macOS shows a security warning, right-click the file, select **Open**, and click **Open** in the dialog. Alternatively, run the following command first:
+
+```bash
+xattr -d com.apple.quarantine ynab-export
+```
+
+#### Step 3: Follow the Prompts
+
+The tool guides you through three steps:
+
+1. **Enter your API token** when prompted. The tool saves it automatically so you will not need to enter it again on future runs.
+2. **Select your budget** from the list of budgets in your YNAB account.
+3. **Wait for the export** to finish.
+
+When done, your budget file is saved to your Downloads folder with a name like `ynab-export-budget-name-YYYYMMDD-HHMMSS.json`.
+
+ </TabItem>
+ <TabItem value="curl" label="cURL">
+
+If you are comfortable with the command line, you can download your budget directly using `curl`.
+
+Before you start, [get your YNAB API token](#getting-your-ynab-api-token) if you have not already.
+
+#### Step 1: Get Your Budget ID
+
+Open a terminal window and run the following, replacing `<ACCESS_TOKEN>` with the token you copied:
+
+```
+curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.youneedabudget.com/v1/budgets
+```
+
+This returns a list of your budgets. Find the `id` for the budget you want to export.
+
+:::note
+To format the output more readably, pipe it to `jq` (install with `brew install jq` on macOS):
+
+```
+curl -sH "Authorization: Bearer <ACCESS_TOKEN>" https://api.youneedabudget.com/v1/budgets | jq -r '.data.budgets | sort_by(.last_modified_on) | reverse | .[] | "\(.name): \(.id)"'
+```
+
+If you see the error `Invoke-WebRequest : Cannot bind parameter 'Headers'` on Windows, use `curl.exe` instead of `curl`.
+:::
+
+#### Step 2: Download Your Budget
+
+```
+curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.youneedabudget.com/v1/budgets/<BUDGET ID> --output budget.json
+```
+
+Replace `<ACCESS_TOKEN>` and `<BUDGET ID>` with your values.
+
+ </TabItem>
+</Tabs>
+
+Once you have the JSON file, proceed to [Import the JSON File](#import-the-json-file).
+
+## Import the JSON File
+
+1. Open Actual
+2. Select the drop-down menu and **Close File**
+3. Select **Import file**
+
+ ![](/img/migrating/actual-import-1.webp)
+
+4. Select **nYnab**
+
+ ![](/img/migrating/actual-import-2.webp)
+
+5. Choose the exported JSON file
+
+## Cleanup
+
+### Credit Cards (Fix Overspending)
+
+If you import credit cards with previous debt, you must handle these differently. Otherwise, your budget months will show overspending. Actual does not handle carrying over debt the same way, but offers a more manual approach.
+
+1. From the Budget screen, create a category named `Credit Card` (perhaps under a Category Group of `Debt`).
+2. Change all overspent transactions to have their category be this `Credit Card` category.
+3. On the first month of overspending for this category, click on the Balance (it should show red) and select `Rollover overspending`.
+4. Next, you must assign money each historical month to cover any payments of the `Credit Card` category. Open YNAB and look through each month to find the "extra" amount assigned to the card. (To find the "extra," open YNAB and look through each month. Find the amount assigned to the card in excess of any additional monthly spending, which is how much was used to pay the debt on the credit card.) Put this amount in your `Credit Card` category in Actual.
+5. If your budget isn't zeroing out yet, follow the instructions below in _Hold For Next Month_.
+
+A full description of how to carry over debt can be found in [our Carrying Debt article.](https://actualbudget.org/docs/budgeting/credit-cards/carrying-debt)
+
+### Hold for Next Month (Fix Money Leftover in To Budget)
+
+nYNAB calculates its `Ready to Assign` value differently than Actual's `To Budget` value.
+There is no need to worry, we can make them match exactly with a simple change.
+This is purely a visual change and doesn't affect the budget itself.
+
+You will likely see money leftover in each of the imported months in your `To Budget`.
+This extra comes from nYNAB including funds budgeted in future months when calculating its `Ready to Assign` value.
+Actual does not include those funds by default, but offers a way to manually reserve funds for use in future months.
+This is effectively the same thing nYNAB does, but in a manual form.
+To `hold` the leftover funds for the next month follow these steps:
+
+1. Click on your `To Budget` value for the month.
+2. Select `Hold for next month`.
+3. Fill in how much you would like to reserve for the future. By default the current `To Budget` value is filled in. Using this value will bring your `To Budget` to zero.
+4. Click `Hold`.
+5. Repeat for all desired months.
+
+A full description of how funds rollover and the `hold` feature can be found in [this article.](../budgeting/#how-money-rolls-over)
+
+### Duplicate Categories or Groups
+
+Actual does not allow duplicate category groups, or duplicate categories within a group.
+This happens sometimes in YNAB especially if you have an old hidden category or group that has been forgotten about.
+Actual automatically renames these duplicates by appending a `-1` to the end of the name (potentially higher numbers if you have multiple duplicates).
+Make sure to show hidden categories to see if you have any of these duplicates.
+To see your hidden categories select the "Toggle Hidden Categories" option in the kebab menu next to the "Categories" header.
+
+#### To fix duplicate groups:
+
+1. Move any categories inside the duplicate group to a different group.
+2. Delete the duplicate group by selecting "Delete" in the menu next to the group name.
+
+#### To fix duplicate categories:
+
+1. Find the duplicate category and select "Delete" in the menu next to the category name.
+2. Choose what category to move any transactions to that are part of this duplicate category.
diff --git a/packages/docs/static/img/migrating/nynab-api-ui-all-plans.webp b/packages/docs/static/img/migrating/nynab-api-ui-all-plans.webp
new file mode 100644
index 0000000000..5ac6dcab01
Binary files /dev/null and b/packages/docs/static/img/migrating/nynab-api-ui-all-plans.webp differ
diff --git a/packages/docs/static/img/migrating/nynab-api-ui-bearer-token.webp b/packages/docs/static/img/migrating/nynab-api-ui-bearer-token.webp
new file mode 100644
index 0000000000..6d9f5dbcf2
Binary files /dev/null and b/packages/docs/static/img/migrating/nynab-api-ui-bearer-token.webp differ
diff --git a/packages/docs/static/img/migrating/nynab-api-ui-download.webp b/packages/docs/static/img/migrating/nynab-api-ui-download.webp
new file mode 100644
index 0000000000..200871a5c3
Binary files /dev/null and b/packages/docs/static/img/migrating/nynab-api-ui-download.webp differ
diff --git a/packages/docs/static/img/migrating/nynab-api-ui-get-plan.webp b/packages/docs/static/img/migrating/nynab-api-ui-get-plan.webp
new file mode 100644
index 0000000000..6892f14d33
Binary files /dev/null and b/packages/docs/static/img/migrating/nynab-api-ui-get-plan.webp differ
diff --git a/packages/docs/static/img/migrating/nynab-api-ui-json-edit.png b/packages/docs/static/img/migrating/nynab-api-ui-json-edit.png
new file mode 100644
index 0000000000..6b7927f922
Binary files /dev/null and b/packages/docs/static/img/migrating/nynab-api-ui-json-edit.png differ
diff --git a/packages/docs/static/img/migrating/nynab-api-ui-pat-token.png b/packages/docs/static/img/migrating/nynab-api-ui-pat-token.png
new file mode 100644
index 0000000000..702244fb18
Binary files /dev/null and b/packages/docs/static/img/migrating/nynab-api-ui-pat-token.png differ