JSON status card

The JSON status card is the power-user escape hatch. It renders a local JSON file as a card of label/value rows with OK, warn and error states. Point any script at the file and its output lands on your desktop.

It is a local widget: it reads a file on your machine and makes no network connection of its own.

What you’ll need

A local JSON status file. Anything that can write a file can feed this widget — a scheduled PowerShell script, a Python cron job, a Home Assistant automation, curl piped through jq.

Set the file path in the widget’s ⚙ panel.

The file format

The root must be a JSON object (not an array). Only items is required to show anything:

{
  "title": "Backup status",
  "updatedAt": "2026-07-25T09:12:00Z",
  "items": [
    { "label": "Last run", "value": "09:12 today" },
    { "label": "Duration", "value": 384, "format": "duration" },
    { "label": "Archive", "value": 5398236160, "format": "bytes" },
    { "label": "Failed sets", "value": 2, "severity": "warn" },
    { "label": "Offsite copy", "value": "stale", "severity": "error" }
  ]
}

Field	Where	Notes
`title`	root, optional	Card heading. Ignored if not a string.
`updatedAt`	root, optional	Shown as the freshness stamp.
`items`	root	Array of rows. Up to 20 are rendered; the rest are ignored.
`label`	item, required	Row label. A row missing `label` or `value` is skipped.
`value`	item, required	String or number.
`severity`	item, optional	`warn` or `error` tone the row. Anything else is treated as normal.
`format`	item, optional	Presentation template — see below.

Formatting values

format lets a script emit raw numbers and leave presentation to the widget, which is usually what you want — it keeps the script free of display logic, and each row formats independently.

`format`	`value`	Renders
`bytes`	`5398236160`	`5.0 GB`
`duration`	`384`	`6m 24s`
`percent`	`0.62`	`62%`
`{v}%`	`62`	`62%`
`{v:.1f} GB`	`7.82`	`7.8 GB`

{v} substitutes the value; {v:.1f} rounds to that many decimals.

A format that isn’t recognised, or a numeric format applied to a non-numeric value, falls back to showing the raw value. A formatting mistake in a status file degrades to plain text — it never blanks the card.

Notes

Write the file atomically if your script runs often: write to a temporary name and rename it into place, so the widget never reads a half-written file.
Invalid JSON leaves the previous card on screen rather than clearing it.

A worked end-to-end example lands with the public beta.