Install on macOS

INSTALL · MACOS

Install Spent on your Mac.

Three commands, about ten minutes. Spent will install itself as a background service and put a small icon in your menu bar.

What you’ll need

• macOS 12 (Monterey) or newer.
• About 500 MB of disk space.
• Your bank login credentials (have them ready).

1. 01

   Install Node.js

   Spent runs on Node.js, a small runtime you install once. Go to nodejs.org, download the LTS installer for macOS, and run it. Click through the defaults.

   If you prefer Homebrew:

   brew install node@20

2. 02

   Get Spent

   Open Terminal (in Applications → Utilities) and clone the repo:

   git clone https://github.com/Shaya16/Spent.git ~/Spent
   cd ~/Spent

   No Git? Install it first with brew install git (after installing Homebrew), then run the clone above.

3. 03

   Install and run setup

   npm install
   npm run setup

   npm install takes 2-3 minutes the first time. npm run setup does everything else: builds the app, installs the background service, builds the menubar, registers everything to start at login, and opens the dashboard.

Note

Setup may pause to install Xcode Command Line Tools if you don’t have them yet. That’s a 1 GB, 5-15 minute system download. You can say no and skip the menubar (web app still installs). Re-run npm run setup later to add it.

What `npm run setup` actually does

In order:

1. Builds the Next.js app (npm run build).
2. Adds 127.0.0.1 spent.local to /etc/hosts so you can reach the dashboard at http://spent.local:41234. Asks for sudo once.
3. Registers a LaunchAgent at ~/Library/LaunchAgents/io.spent.app.plist that starts the server on login. Server binds to 127.0.0.1:41234 only.
4. Builds Spent.app from menubar/mac/ (Swift). Needs Xcode Command Line Tools (offered for install if missing).
5. Copies Spent.app to ~/Applications/ and registers it as a Login Item so the menubar shows up after reboot.
6. Polls /api/health until the server is ready, then opens the browser.

Source: scripts/setup.mjs.

First launch

The first time you click the menubar icon, macOS Gatekeeper will balk:

Heads up

“Spent.app can’t be opened because it is from an unidentified developer.” — Right-click Spent.app in ~/Applications, choose Open, then Open in the dialog. After the first launch, double-click works normally.

Day-to-day commands

Once installed, you mostly forget the terminal. But these are useful:

npm run service:status   # is the background service running?
npm run service:start    # start it
npm run service:stop     # stop it
npm run service:reload   # rebuild + restart (after a code change)
npm run service:logs     # tail the server logs
npm run service:open     # open the dashboard in the browser

Uninstall

To remove the service, hosts entry, menubar, and login item:

npm run uninstall

Your data/ folder is left alone so you can reinstall later.

Next Connect your bank →