Where your data lives

Pulsaria has no database and no server. Everything you enter lives in readable JSON files in one folder on your Mac, written with two-space indentation so you can open them in any text editor. This page tells you exactly which folder, what is in it, and what happens when you move it.

The default folder

Unless you change it, Pulsaria writes to its own application support folder:

~/Library/Application Support/com.onepixelahead.pulsaria/pulsaria/

In Finder you can jump there with Go → Go to Folder… and paste the path.

To see which folder is in use, open App Settings and find the card Data Directory. The field Current Path shows the folder. When it is empty it displays the placeholder Default (AppData), which means the path above. The card only appears in the desktop app.

What is in the folder

File or folder	What it holds
projects.json	Every project: name, description, status, creation date
kpi-definitions.json	Every KPI definition: name, unit, target, direction, period, metric kind, data source and its configuration, optional cron schedule, approval stamp
entries/	One file per recorded measurement — see below
alerts.json	Status-change alerts, newest first, capped at the last 100
fetch-log.json	The fetch log, newest first, a ring buffer capped at 500 entries
reminder-settings.json	The daily reminder: on/off, time, “only if a value is missing”. If the file is missing, Pulsaria falls back to off, 18:00, only-if-missing

Those six items are the ones the data-directory setting controls. They move with you when you point Pulsaria somewhere else.

What stays behind

These stay in the application support folder no matter what you set as your data directory:

Location	What it holds
…/com.onepixelahead.pulsaria/pulsaria/config.json	All app settings: the data directory itself, theme, language, crash-reporting consent, dismissed hints, onboarding and tour flags, collapsed dashboard groups, and the daily auto-export settings and status
…/com.onepixelahead.pulsaria/pulsaria/connections.json	Your connector connections — which connector, connection name, parameters, and the name of the Keychain item that holds the secret
…/com.onepixelahead.pulsaria/pulsaria/license.json	Your licence key, the activation for this machine, and the result of the last validation
…/com.onepixelahead.pulsaria/pulsaria/daily-export/	Default target of the daily auto-export
~/.pulsaria-trial	A one-line dotfile that anchors the trial start date

Connector credentials are in no file at all. API keys, tokens and service-account JSON go into the macOS Keychain under the service com.onepixelahead.pulsaria, with one item per connection named connection.<connection-id>. See Privacy: what leaves your Mac.

Nothing Pulsaria writes is encrypted. The JSON files are plain text, readable by anything running under your macOS account. The only exception is the connector secrets, which are protected by the Keychain.

One file per measurement

Every value you record — typed by hand or fetched automatically — becomes its own small file in entries/:

2026-07-25_kR7fQ2mXa1_1784970824812_3.json

The parts are the local date, the KPI id, the epoch milliseconds of the write, and a counter that keeps two writes in the same millisecond apart. Any character in the KPI id that is not A–Z, a–z, 0–9, _ or - becomes _. The content is exactly three fields:

{
  "kpiId": "kR7fQ2mXa1",
  "value": 12400,
  "createdAt": "2026-07-25T09:13:44.812Z"
}

Files are only ever added, never rewritten. That is the point of the design: correcting a KPI on a day you have already filled in does not overwrite the old file, it writes a new one next to it. Two Macs writing into a shared folder on the same day produce two different files instead of clobbering each other.

What you see follows from that:

• The dashboard and the history use the entry with the newest createdAt for that KPI on that day.
• The earlier files stay on disk. They show up in the intraday view on the KPI detail page and in every export.
• Deleting a day’s value or a whole KPI deletes the matching entry files for real.

One thing to know before you go looking for old numbers: the app builds charts and history from the 90 most recent dates that carry any entry at all, counted across all KPIs. Everything older is still on disk and still in every export — it is just not drawn.

More on how values get there: Entering values.

Migration from the old per-day format

Older installs stored one file per day, 2026-07-25.json, holding an array of that day’s entries. Pulsaria converts that format the first time it reads entries after launch, once per session: each entry in the array becomes its own file named <date>_<kpiId>_<epoch-ms>.json (no counter suffix — that is how you can tell migrated files apart), and the old day file is then removed.

A legacy file that cannot be read or cannot be parsed is left exactly where it is and skipped. It is never deleted on the assumption that it was empty. The migration is best-effort as a whole: if it fails, the app carries on with whatever it could read.

Crash-safe writes and corrupt-file quarantine

Writes to the files listed in the first table go through two safety nets.

Atomic write. New content goes to a uniquely named temporary file — <file>.<epoch-ms>.<counter>.tmp — which is then renamed over the target. A crash or a power loss between the two steps leaves the previous file completely intact instead of a half-written one. If the write fails, the temp file is removed again.

Quarantine. Before overwriting, Pulsaria checks whether the existing file parses as JSON. If it does not, the damaged bytes are moved aside first:

projects.json.corrupt-2026-07-25T09-13-44-812Z

Meanwhile the app keeps running with empty data for that one file, so a corrupt alerts.json does not stop you from working. The quarantined copy sits next to the original in Finder — open it, salvage what you need, rename it back if you can repair it.

The safety nets cover projects.json, kpi-definitions.json, alerts.json, fetch-log.json, reminder-settings.json and the entry files. They do not cover config.json, connections.json and license.json: those are written with a plain overwrite, and a connections.json that cannot be parsed is read as “no connections” and then overwritten with no copy kept. If that happens you lose the connector connections and have to set them up again. Regular exports are the protection here — see Backup, export & moving Macs.

Moving the data folder

1. Open App Settings and go to the card Data Directory.
2. Click the folder button to the right of Current Path and pick the folder in the macOS dialog titled Choose Data Directory.
3. Click Save. The button briefly shows a checkmark and Saved, and the app immediately re-reads its data from the new location.

Use Default clears the field; after Save you are back on the built-in application support folder. The new folder and its entries/ subfolder are created on the first write.

Use the folder picker, not the text field

The Current Path field is editable, and typing a path into it will not work. Pulsaria’s built-in file-system permissions cover only its own application support folder. Access to anywhere else is granted at runtime by the macOS folder dialog, and only for the folder you actually picked in it — that grant then persists across restarts. A hand-typed or pasted path gets no such grant, so writes fail and the app looks empty even though your old data is still safe in the old place.

If you have already typed something and saved it, open the card again, click the folder button, pick the same folder properly, and save once more.

Moving does not move anything

Saving a new data directory re-points the app and nothing else. Pulsaria does not copy your files, does not move them, does not merge them, and does not offer to. Right after the switch the new folder is empty and the dashboard looks like a fresh install; the old folder is untouched.

To take your data with you, pick one:

• Quit Pulsaria, copy the six items from the old folder into the new one in Finder, then start the app and point it at the new folder.
• Or use Export JSON before the switch and Import JSON afterwards, described in Backup, export & moving Macs.

Either way, config.json, connections.json and license.json stay where they are. Your settings and connector connections are not affected by the move — and are not carried along by it either.

About the “Use iCloud” button

The card has a button labelled Use iCloud. It fills the Current Path text field with a suggested path into a private iCloud container and nothing more. It does not open a folder dialog, so it grants no file-system access — which puts it in exactly the category described above: a path in the text field that Pulsaria is not permitted to write to.

Use the folder button for iCloud, not the Use iCloud shortcut. Pick a normal folder under ~/Library/Mobile Documents/com~apple~CloudDocs/ — for example one you created in Finder under iCloud Drive. That route goes through the dialog, so the permission grant is real and survives restarts.

Sharing one folder between two Macs

Pointing two Macs at the same synced folder works, within limits you should know before you rely on it.

What holds up. Measurements are append-only, one file per entry, so both machines can record values on the same day without overwriting each other. File deletions propagate like any other change.

What does not. projects.json, kpi-definitions.json, alerts.json and fetch-log.json are single files: the last writer wins. Rename a KPI on one Mac while the other Mac is also writing, and one of the two edits is gone. Pulsaria has no merge logic and ignores conflict copies — a file that iCloud renames to projects 2.json is simply not read.

No live updates. There is no file watcher. Pulsaria re-reads from disk when a screen mounts and when something inside the app changes data, not when another machine writes into the folder. Switch screens or restart the app to pick up remote changes; the Refresh button in the dashboard header also causes a re-read, though its actual job is fetching auto-KPIs. There is no lock file, no sync indicator and no “last synced” line anywhere in the app.

Not shared at all. Settings, connector connections and the licence stay in each Mac’s own application support folder. Connector credentials live in each Mac’s own Keychain, so a connection set up on one machine needs its key entered again on the other.

If you mainly want your numbers on a second Mac rather than continuous two-way sync, exporting and importing is the more predictable route.

What to back up

The short version: back up the whole data folder, and export regularly.

• Time Machine or any backup tool pointed at ~/Library/Application Support/com.onepixelahead.pulsaria/ catches everything Pulsaria writes, including config.json, connections.json and license.json. If you moved your data directory, back up that folder too.
• Export JSON from App Settings → Export data gives you one restorable file. Turn on Daily auto-export in the same screen to have it written for you every day.
• Export is not licence-gated. Export JSON and Export CSV stay clickable after the trial ends, so you can always get your data out.

What an export does not contain: connector credentials (Keychain only), everything in config.json, the reminder settings, and the licence file. Details in Backup, export & moving Macs.

Where to go next

• Backup, export & moving Macs — export formats, import with conflict resolution, daily auto-export
• Privacy: what leaves your Mac — which requests go out and what is stored where
• Settings — the full App Settings screen
• Fetch log — what fetch-log.json records
• Troubleshooting — empty dashboard, failed writes, missing values