Your first KPI

This page walks one KPI from nothing to a working card on your dashboard. It takes about five minutes. The first walkthrough is a manual KPI — a number you type in yourself. The second is a connector KPI, which fetches its own value.

If Pulsaria is not installed yet, start with Install & first launch.

Create a project (optional)

A KPI is either Company-wide or attached to one project. Company-wide is the default, and you can move a KPI later, so you can skip this section entirely and come back to it when you have more than a handful of KPIs.

1. Click Projects in the sidebar.
2. Click New Project (top right).
3. Fill in Name — the only required field, placeholder e.g. Growth 2026.
4. Optionally add a Description and pick a Status: Active, On Hold or Completed. New projects start as Active.
5. Click Create Project.

The project immediately gets its own section on the dashboard, with its own + KPI button — even before it contains anything.

Deleting a project deletes every KPI inside it and all of their recorded values. There is no undo. Use projects for grouping, not as a folder you tidy up later.

More on this in Projects.

Create a manual KPI

On a brand-new install the dashboard shows a welcome panel with three buttons: Create project, Create KPI and Use a template. As soon as one KPI or one project exists, that panel is replaced by grouped sections, each with a + KPI button in its header.

1. Open the dashboard and click Create KPI (fresh install) or + KPI in the header of the group you want the KPI to belong to. The group you click decides the pre-selected scope.
2. The dialog opens on the question “Where does this KPI’s data come from? You can change this later.” with four cards: Manual, Connector, Bash, HTTP. Click Manual.
3. The form appears, split into a Data source section (for a manual KPI just a one-line note) and a Goal section. Fill in the Goal fields — see the table below.
4. Click Create KPI.

You get a “KPI created” toast, the dialog closes, and the card appears in its group right away.

The Goal fields

Field	What it does
Name	Required. Free text, placeholder e.g. Revenue Growth. Empty name blocks saving with “Name is required”.
Unit	Free text, pre-filled with %. It is printed next to every number — EUR, hours, count, orders, whatever you like. Never validated, so an empty unit saves fine.
Target	Required. Must be a number greater than 0, otherwise “Target must be a number greater than 0”.
Direction	Higher is better (default) or Lower is better. This flips the whole colour logic — for a “lower is better” KPI, being under the line is good.
Scope	Company-wide or one of your projects.
Period	Year, Month, Quarter or Custom range. Picking Custom range reveals Start date and End date, both required.
KPI type	Cumulative goal (default) or Recurring value. See below.

Errors appear once you leave a field or press the save button, not while you type.

The Target field is a plain number field. The value fields on Daily Entry understand both 1.234,56 and 1,234.56; the target field does not go through that parser, so type it the way your system’s number field expects.

Cumulative goal or recurring value

This choice decides what Pulsaria compares your value against, and it is the one setting people get wrong on their first KPI.

• Cumulative goal — “Value accumulates toward target (e.g. revenue)”. The number you record is a running total for the period, and the reference line grows evenly from 0 on the first day to the target at the end. Revenue, new signups, hours logged.
• Recurring value — “Fresh reading each period against a benchmark (e.g. MAU)”. Every reading stands on its own and is compared against a flat benchmark: the target itself, on every day. Active users, conversion rate, response time, churn.

You can change this later, but the change re-grades the whole history — the old grading is not kept anywhere.

Period

Year, Month and Quarter always mean the current calendar year, month or quarter, and they roll over on their own: a monthly KPI starts a fresh reference line on the 1st. There is no week period and no fiscal-year offset — Custom range is the only way to point a KPI at a window of your own choosing.

Details in Periods & targets.

Enter today’s value

1. Click Daily Entry in the sidebar.
2. The Date picker at the top defaults to today. Leave it.
3. Pick a Scope: All scopes, Company-wide or a project, each with its KPI count in brackets.
4. Under Manual KPIs each row shows the KPI name, its target and unit, the direction arrow and Last value. Type your number into the field on the right.
5. Save either the single row — the check button next to the field — or every filled row at once with Save All Entries at the bottom.

A saved row flashes green for two seconds and a Saved at HH:MM note appears next to the button. Empty rows are skipped silently; a row you filled with something unparseable is reported as “1 value wasn’t a valid number and was skipped”.

Number formats: 2,5, 2.5, 1.234,56 and 1,234.56 all parse correctly. The genuinely ambiguous case — one separator followed by exactly three digits, like 2.810 — is resolved by the app language: German reads the dot as a thousands separator, English reads the comma that way.

Manual rows never pre-fill with a value you already saved for that day, and the Auto KPIs section always shows today’s values even if you picked an earlier date. The date picker controls where a new value is written, not what the page displays.

The other way: from the KPI page

Click the card to open the KPI, then press Add value in the header row. That writes today’s date. To correct an older day, scroll down to the History table and use the pencil on that row.

You can record several values for the same KPI on the same day — nothing is overwritten on disk, but for every chart, status and comparison, the latest entry of that day is the one that counts.

More in Entering values.

Read the card

Take a company-wide KPI called Monthly revenue: unit EUR, target 8000, Higher is better, period Month, type Cumulative goal. It is 10 July, and you just recorded 3200.

The card now shows, top to bottom:

• Name and status dot. The dot is green (On track), amber (At risk) or red (Off track).
• The value, large, with the unit beside it: 3,200 EUR. Amounts in EUR, USD, GBP, CHF, € and $ are shown without decimals from 1,000 upwards, with exactly two below that.
• The gap badge, e.g. +38% vs ideal. That is how far you are from where the reference line sits today. Green when ahead, amber when less than 10 % behind, red at 10 % or more behind.
• The week badge, e.g. +12% vs. previous week — the latest value against the newest value that is at least seven days older. It is simply absent until the KPI has two recorded days far enough apart.
• The sparkline, covering the whole period (1–31 July here) with your values as a filled line and the reference line dashed in grey.
• The footer: 8,000 EUR/mo on the left, ideal: 2,323 EUR on the right.

Where does 2,323 come from? Nine days have elapsed since 1 July, and 8,000 ÷ 31 × 9 = 2,322.58. With 3,200 recorded you are 877.42 above that line, which is +38 %, which is green.

For a Recurring value KPI the footer reads target: instead of ideal: and the badge reads vs target, because the reference line is flat at the target.

What the numbers mean on day one

On the first day of a cumulative period the reference line is exactly 0, so the gap badge is hidden on the card and every non-negative value counts as On track. That is arithmetic, not optimism — the line only becomes meaningful from day two.

A KPI with no values at all shows an em dash, a neutral grey dot and the hint Add today’s value.

The full anatomy is in Dashboard and KPI detail; the grading rules are in Ideal line & status.

A connector KPI in six steps

A connector KPI pulls its number from a service you already use — Google Search Console, Google Analytics 4, Plausible, Polar, Stripe or Awin. The flow is the same dialog, with two extra pickers in front of it.

1. Click + KPI as before and pick the Connector card. The Connector Library opens by itself.
2. Search, or click a service on the left and one of its metrics on the right. Click Use selected metric.
3. Pulsaria asks for a connection — the credentials for that service. Pick an existing one, or click Create a new connection and run the short setup wizard. Keys and service-account files go into your macOS Keychain, not into Pulsaria’s own files.
4. Back in the KPI dialog, the metric has filled in unit, direction, KPI type and, where the metric defines them, period and cron schedule. The name is filled in only if you left it blank.
5. Set your Target and Scope, and check the Cron schedule. This is the field that decides when the value is fetched.
6. Click Create KPI.

Connector KPIs need no approval step — unlike Bash and HTTP sources, which ask you to inspect and approve the exact command or URL before they ever run.

Two things to know before you rely on it. A connector KPI saves even when no metric or no connection is selected — the form only checks name, target, period and cron — and it then simply never fetches. And a KPI saved with an empty cron schedule is never picked up by the scheduler; it only updates when you press Run now on the KPI or Refresh on the dashboard.

Scheduled fetches happen while Pulsaria is running. Everything about credentials, metrics and per-service quirks lives in Connectors; everything about timing in Schedules & refresh.

Where to go next

• Anatomy of a KPI — every field, in reference form.
• Ideal line & status — why a card is amber and not green.
• Data sources at a glance — manual, connector, shell or HTTP, and when to use which.
• Trial & licence — creating and editing needs an active trial or licence; without one, most buttons carry the tooltip “Requires a license or active trial”.