Skip to content
Docs0.9GitHubInstall

Using itHUD sections

HUD sections

A command section of the HUD shows what a program of yours prints.

[[plugins.hud.sections]]
type = "command"
name = "ci"                       # lowercase letters, digits, hyphens
command = ["/home/you/bin/ci-hud", "--branch", "main"]   # argv, not a shell line
interval_seconds = 30             # run again this long after it exits; 1–86400

The HUD starts the program with stdin closed and VENDETTA_HUD_SECTION set to the section’s name; its stderr goes to the worker’s log. Each line it prints on stdout is one JSON section that replaces what the card shows. A program can print once and exit, to run again after interval_seconds, or keep running and print a line whenever something changes. It ends with the HUD.

{
  "title": "CI",
  "icon": "◆",
  "summary": [{"text": "1 failing", "color": "error"}],
  "rows": [
    {
      "icons": [{"text": "●", "color": "#f38ba8"}],
      "text": "vendetta main",
      "detail": "failed 3m ago",
      "tooltip": "Build 1842",
      "command": ["xdg-open", "https://ci.example.com/builds/1842"]
    }
  ],
  "empty": "All green",
  "footer": "+2 more"
}

Every field is optional.

Field Meaning
title The header’s title; the section’s name when empty.
icon A glyph before the title.
summary Text at the right of the header, shown while minimized too.
rows Up to 50 rows.
empty Shown when there are no rows.
footer Text under the rows.
error Shown instead of the rows.

A row has icons (up to four glyphs, each in a narrow column), text, detail (at the right), note (shown whole under the row, keeping its lines, up to 4,096 characters), tooltip, and command: an argv that runs, detached and without a shell, when the row is clicked.

Text is a string, or a list of spans {"text": "…", "color": "…"}, each also "bold", "italic", or "code" (monospaced) when true. A color is #rrggbb, or a role that follows Noctalia’s theme: primary, text, muted, or error. Text is shown literally, never as markup; control characters are dropped, and long text is cut.

A line that is not a valid section, or a program that fails before printing one, shows the error in the card. Lines are at most 256 KiB.

#!/bin/sh
# Free space on /, every minute: interval_seconds = 60.
used=$(df --output=pcent / | tail -1 | tr -dc 0-9)
color=muted; [ "$used" -ge 90 ] && color=error
printf '{"title":"Disk","icon":"▤","summary":[{"text":"%s%% used","color":"%s"}]}\n' "$used" "$color"