Skip to content

Desktop App

Jump to bottom
brookie edited this page Nov 7, 2026 · 5 revisions

Desktop App

Financial Planner app icon

On a Mac, Financial Planner can run as a regular app: an icon in Applications that opens the planner in your browser and lives in the menu bar. No terminal needed.

Contents

Install (no code)

  1. Download the zip for your Mac from the Releases page: arm64 for Apple Silicon (M1 and later), x86_64 for Intel.
  2. Unzip it and drag Financial Planner into Applications.
  3. The first time, right-click the app → Open → Open (the app isn't signed by Apple yet, so macOS asks once).

First launch

  1. A "Setting up Financial Planner" message appears while it downloads what it needs (a few minutes, once; needs the internet).
  2. It asks how you'd like to start:
    • Start a new plan: a new, empty plan in FinancialPlan in your home folder.
    • Open a plan someone shared with me: pick the .zip they sent (see Share the whole plan).
    • Use a plan folder I already have, or choose where to start one: a folder picker.
    • Try the demo: a fictional household in ~/FinancialPlan-Demo, to look around.
  3. The planner opens in your browser and the icon appears in the menu bar. Continue with the Quick Start from "Add your household".

Your choice is remembered; later launches open straight to your plan.

Everyday use

Open Financial Planner from Applications, Launchpad, Spotlight (⌘ Space, "Financial Planner") or the Dock (right-click its Dock icon → Options → Keep in Dock).

The menu-bar icon

The icon menu-bar icon sits at the top right of the screen while the app runs.

Item What it does
Open Financial Planner Opens the planner in your browser.
Financial Planner 0.x.y The version you're running.
Plan: … Which plan folder is open.
Change Plan Folder… Open another plan (or turn an empty folder into a new one).
New Plan… Create a new blank plan in a folder you pick.
Show Plan Folder Opens the plan folder in Finder (to add CSV files, for example).
Open Plan File… Open a whole plan someone sent you (a .zip); keep both or replace yours (yours is kept as a backup).
Save Plan as File… Save your whole plan as one .zip to send to someone.
Check for Updates… Checks for a newer version; if there is one, installs it and restarts the app.
Uninstall… Removes the app and its downloaded files. Your plans are kept.
Quit Financial Planner Stops the planner.

Opening and closing

  • Only one copy runs. Opening the app again just opens a browser tab on the running planner.
  • Closing the browser tab doesn't stop it: the planner keeps running in the menu bar, ready for the next click (like a music app with its window closed).
  • Quit from the menu-bar icon (or the Dock) stops it completely. If the app ever crashes or is force-quit, the planner stops by itself within a couple of seconds.

Sharing a plan

  1. Send: menu-bar icon › Save Plan as File… saves one .zip (settings, categories and rules, CSV data, planner edits and scenarios). Send it by AirDrop or Messages.
  2. Open: menu-bar icon › Open Plan File… (or, on a first launch, Open a plan someone shared with me). Choose Keep Both or Replace; replacing keeps the old plan as a backup folder next to it.

The file contains your real transactions, so share it privately. Details: Share the whole plan.

Updating

Menu-bar icon › Check for Updates…. It checks for a newer release:

  • Up to date: it says so and shows your version.
  • A newer version: it shows both versions and asks. Click Update; it downloads the new version (about a minute) and restarts itself. Your plans and settings are untouched.

The version you're running is shown in the menu ("Financial Planner 0.x.y").

If you already have the code

With the repository and pixi set up (Installation), one command puts a Financial Planner app in /Applications that uses your existing environment:

pixi run financial_plan launcher

It works the same way (menu-bar icon, first-launch folder choice, single instance). To build the full no-code app instead, see installer/README.md in the repository (bash installer/macos/make-local-app.sh).

Uninstalling

Menu-bar icon › Uninstall…. It lists what it removes and asks first:

  • the app,
  • its downloaded files and logs (~/Library/Application Support/FinancialPlanner),
  • the setting that remembers which plan to open.

Your plans are never removed; the dialog shows where the current one is. A notification confirms when it's done.

From a terminal instead (quit the app first):

financial_plan uninstall

Or by hand: quit the app, drag it to the Trash, and delete ~/Library/Application Support/FinancialPlanner (Finder: Go › Go to Folder…).

Troubleshooting

Problem Fix
"Can't be opened because it's from an unidentified developer" Right-click the app → Open → Open (once).
Setup failed Check the internet connection and open the app again. Details: ~/Library/Application Support/FinancialPlanner/launch.log.
The planner didn't start server.log in the same folder says why (often a config problem; fix it in Settings or the YAML).
No menu-bar icon It may be hidden behind the notch or other icons; quit other menu-bar apps or use a menu-bar manager. Opening the app again still opens the browser.
Want to switch plans Menu-bar icon → Change Plan Folder…

Windows and Linux

The no-code app is macOS-only for now. On Windows and Linux, financial_plan launcher creates a .bat / .desktop shortcut that starts the planner (see Command Line).

🏠 Home

Getting started

Using the app

Setting up your plan

Reference

Clone this wiki locally