=== BalVault — Spreadsheet Integration Guide ===

BalVault writes your account balances to a CSV file (accounts.csv).
Default location: Documents\BalVault\accounts.csv

CSV columns:
   A: Name          B: Type        C: Institution
   D: Balance       E: Available   F: Balance Date

Column F shows when the bank last updated that balance, per
SimpleFIN, in your local timezone (e.g. "2026-07-28 15:42:00 EDT").
If the bank doesn't report a balance date, BalVault falls back to
its own fetch time — so column F is never blank. Column C shows the
bank/connection name SimpleFIN reports, and column E is the
available balance (equal to the balance when the bank doesn't
report a separate one).


─── 1. First-Time Setup ─────────────────────────────────────

1. Download and extract BalVault.zip (from balvault.com/download)
2. Run BalVaultStart.bat — it installs BalVault to Program
   Files\BalVault, creates Start Menu and Desktop shortcuts,
   and opens the BalVault setup window
3. Get your SimpleFIN Bridge setup token from bridge.simplefin.org
   ($1.50/month, billed by SimpleFIN — required for bank access)
4. Paste the token into BalVault's setup page and click Save
5. BalVault will validate the token and confirm how many accounts
   it found. Then press Enter to write your first accounts.csv —
   or run it from your spreadsheet.
6. Change CSV location (press F or click "Change CSV location")

BalVault runs in its own app window — no browser tabs or address
bar — and no console window ever appears while it runs.

When a newer BalVault release is available, just extract it and
run BalVaultStart.bat again — it compares the version and updates
your installation automatically.

After first run, the extracted folder is automatically deleted.
Use the Start Menu or Desktop shortcut for future runs.

Where things live:
  • BalVault program files:  Program Files\BalVault
  • Your data (accounts.csv): Documents\BalVault\accounts.csv
  • Launcher, uninstaller, this guide, refresh macro and
    template: Documents\BalVault
  • Setup token and account database: ~\.balvault (hidden)


─── 2. Automation Options ────────────────────────────────────

Option A: Silent background fetch (no UI, auto on spreadsheet open)

  Sets up a LibreOffice macro that runs BalVault invisibly every
  time you open your budget spreadsheet. Column F in the CSV shows
  when the bank last updated each balance (per SimpleFIN), falling
  back to BalVault's fetch time when the bank doesn't report one.

  To set up, see the LibreOffice Calc section → Macro Setup.

  The macro uses BalVault's --auto flag: no browser opens, no
  window appears. BalVault starts, fetches, writes the CSV, and
  exits silently in under 10 seconds.

Option B: Manual fetch with the BalVault window (see what's happening)

  Click the Desktop or Start Menu shortcut. BalVault opens in its
  own app window — no browser tabs, no address bar, and no console
  window. Errors are displayed in red on screen. The app window
  closes automatically after a successful fetch, or stays open if
  something went wrong.

Choose Option A if you want everything automated. Choose Option B
if you prefer to see BalVault running and want error visibility.


─── 3. LibreOffice Calc ──────────────────────────────────────

One-time data link setup:
  1. Open your budget spreadsheet in LibreOffice Calc
  2. Insert → Sheet From File
  3. Browse to Documents\BalVault\accounts.csv
  4. Check the "Link" box → click OK
  5. A new sheet named "accounts" appears with live-linked data

Easiest way: use the ready-made template

  BalVault ships with a ready-made budget template:
    Documents\BalVault\BalVault-Template.ods
  (same folder as accounts.csv). The macro below is already set up
  in the template file — BalVaultRefresh is installed, the Open
  Document event is connected, AND the "accounts" sheet is already
  linked to accounts.csv. The CSV link is relative, so it works
  wherever the template and accounts.csv sit together — there is
  nothing to configure.

  Steps:
  1. Open BalVault-Template.ods in LibreOffice Calc
  2. File → Save As → your budget file name (e.g. MyBudget.ods).
     Save it in Documents\BalVault (next to accounts.csv) so the
     existing CSV link keeps working.
  3. Done. Every time you open the file, the macro runs BalVault
     invisibly if the CSV is stale and refreshes the linked
     "accounts" sheet automatically.

  If you changed the CSV location in BalVault (press F) or saved
  your spreadsheet in a different folder, re-link the accounts
  sheet once: Insert → Sheet From File → your new accounts.csv
  path → check the "Link" box → OK.

  If macros are blocked, use Tools → Options → Security → Macro
  Security to allow macros for this document (or a trusted location).

  The manual steps below are for adding the macro to an EXISTING
  budget file that can't use the template (for example, the owner's
  own multi-sheet budget file).

Macro setup (auto-refresh on open):

  BalVault ships with a ready-to-use Calc macro that checks whether
  accounts.csv is stale (last-modified before today) and, if so,
  runs BalVault silently.  Errors are shown in a message box.

  The macro file:  BalVaultRefresh.bas — it is placed in the same
  folder as accounts.csv (Documents\BalVault\BalVaultRefresh.bas
  with the default CSV location).

  Steps:
  1. Save your spreadsheet as .ods (CSV cannot store macros).
  2. Tools → Macros → Organize Macros → Basic...
  3. In the left pane, expand your .ods file → select "Standard".
  4. Click "New" to create a module.  Name it "BalVaultRefresh".
  5. Open BalVaultRefresh.bas (the copy in the same folder as
     accounts.csv, e.g. Documents\BalVault\BalVaultRefresh.bas) in
     Notepad, copy ALL of it.
     Don't use Import. Only Notepad-copy-paste into an emptied
     module: select the module's default stub (Ctrl+A), delete it,
     then paste.
  6. Click the Save icon in the Basic IDE toolbar, then close it.
  7. Tools → Customize → Events tab.
  8. Click "Open Document" → "Macro..." button.
  9. In the macro selector, expand your .ods file → Standard →
     BalVaultRefresh → Main.  Click OK.
  10. Click OK again to close Customize.  Save the file.

  Test it: close the spreadsheet and reopen it.  If the CSV is
  older than today, BalVault runs invisibly, then the linked
  "accounts" sheet is refreshed automatically — the sheet shows
  fresh data on the same open.  Check column F for the balance date
  (when the bank last updated each balance).

  The auto-refresh works when the "accounts" sheet was linked with
  the "Link" box checked as shown above.  If a sheet still shows
  old data, use Edit → Links to External Files → Update.

  The macro handles these cases automatically:
    • CSV missing → runs BalVault to create it
    • CSV modified today → does nothing (already fresh)
    • BalVault.exe not found → message box with the expected path
    • BalVault exits with error → message box with the exit code
    • Successful run but no CSV → message box (skipped when
      BalVault opened its own window to explain the problem)

  Advanced: set the BALVAULT_CSV or BALVAULT_EXE environment
  variables to override the default paths before launching Calc.

Using in formulas:
    =accounts.D2          (Chase balance)
    =SUM(accounts.D2:D10) (all balances)
    =accounts.F3          (balance date)

Lookup by account name (rows may shift):
    =VLOOKUP("Chase Checking";accounts.A:D;4;0)
    =INDEX(accounts.D:D;MATCH("Chase Checking";accounts.A:A;0))
    =SUMIF(accounts.A:A;"*Savings*";accounts.D:D)

Refresh linked data after a manual BalVault run:
   Edit → Links to External Files → Update
   (Or close and reopen the spreadsheet)


─── 4. Microsoft Excel ───────────────────────────────────────

One-time setup:
  1. Open your budget spreadsheet in Excel
  2. Data → Get Data → From File → From Text/CSV
  3. Browse to Documents\BalVault\accounts.csv → Import
  4. In the preview, click "Load" (or "Load To..." to choose a sheet)
  5. When prompted, click "Trust" or "Refresh" on open to keep data current

Using in formulas (if loaded to a sheet named "accounts"):
    =accounts!D2          (Chase balance)
    =SUM(accounts!D2:D10) (all balances)
    =accounts!F3          (balance date)

Lookup by account name (rows may shift):
    =VLOOKUP("Chase Checking",accounts!A:D,4,FALSE)
    =INDEX(accounts!D:D,MATCH("Chase Checking",accounts!A:A,0))
    =SUMIF(accounts!A:A,"*Savings*",accounts!D:D)

Refresh after a BalVault run:
   Data → Refresh All
   (Or right-click the data range → Refresh)


─── 5. Google Sheets ─────────────────────────────────────────

One-time setup:
  1. Open your budget spreadsheet in Google Sheets
  2. File → Import → Upload → browse to Documents\BalVault\accounts.csv
  3. Choose "Replace current sheet" or "Insert new sheet"
  4. Check "Link to spreadsheet" if you want auto-refresh
     (requires Google Drive desktop sync to keep the CSV local)

Using in formulas (if imported to a sheet named "accounts"):
    =accounts!D2          (Chase balance)
    =SUM(accounts!D2:D10) (all balances)

Lookup by account name (rows may shift):
    =VLOOKUP("Chase Checking",accounts!A:D,4,FALSE)
    =INDEX(accounts!D:D,MATCH("Chase Checking",accounts!A:A,0))
    =SUMIF(accounts!A:A,"*Savings*",accounts!D:D)

Refresh after a BalVault run:
   Re-import the file (File → Import) with the updated CSV


─── 6. Apple Numbers ─────────────────────────────────────────

One-time setup:
  1. Open your budget spreadsheet in Numbers
  2. Drag accounts.csv from Finder onto the sheet canvas
  3. Or: File → Open → browse to Documents\BalVault\accounts.csv
  4. Copy/paste the data into your main budget sheet

Using in formulas:
   Reference cells directly by clicking them, e.g.:
    =Sheet 2::Table 1::D2

Refresh after a BalVault run:
   Re-import the updated CSV file (drag it in again)
   Numbers does not support live-linked CSV files


─── 7. OnlyOffice ────────────────────────────────────────────

One-time setup:
  1. Open your budget spreadsheet in OnlyOffice
  2. Data → From Text/CSV
  3. Browse to Documents\BalVault\accounts.csv → Open
  4. Configure delimiter (comma) and encoding (UTF-8) → OK

Using in formulas:
   Reference cells normally, e.g.:
    =D2          (if data is on the same sheet)
    =Sheet2!D2   (if on another sheet)

Refresh after a BalVault run:
   Re-import the updated CSV (Data → From Text/CSV)
   OnlyOffice does not support live-linked CSV refresh


─── 8. Generic: Any Spreadsheet ──────────────────────────────

accounts.csv is a standard comma-separated text file. Any spreadsheet
app can open it: File → Open → browse to the CSV.

Even Notepad works for a quick balance check.
Use your app's "Import CSV" or "From Text" feature for the cleanest
column detection.


─── !!! CAUTION: Keep Your Data Local !!! ─────────────────────

BalVault is designed to keep your financial data private. Your
SimpleFIN setup token and account database are stored ONLY on your
computer — nothing is ever sent to our servers or to any cloud.
On Windows, the setup token and the SimpleFIN access URL are
encrypted at rest with Windows DPAPI (per-user), so the plaintext
secret never sits on disk. The account balances themselves stay in
the local database and the CSV you choose.

accounts.csv contains your real account balances. If you move that
file into a cloud-synced folder (Google Drive, OneDrive, iCloud,
Dropbox, etc.), your financial data WILL be uploaded to those services.

  • DO keep accounts.csv on your local drive
  • DO NOT set your CSV location to a cloud-synced folder
  • The default location (Documents\BalVault\) is local-only

Even with the file on your local drive, you can still link it into
any spreadsheet app — Calc, Excel, and Sheets all support local CSV
import without uploading anything.


─── Quick Tips ────────────────────────────────────────────────

  • Change your CSV location by pressing F in BalVault
  • You can change your CSV location anytime — it persists between runs
  • Keep the path local — avoid synced folders for privacy
  • Press Enter to update your CSV, then the app closes
  • Press Esc to exit without updating
  • Check column F for the balance date — when the bank last
    updated each balance, per SimpleFIN (BalVault's fetch time if
    the bank doesn't report one)


─── Support ──────────────────────────────────────────────────

  Need help? Visit balvault.com/support
  to send us a message. We'll get back to you within 24 hours.
