mainskeeper command line

Monitoring only

There are no shutdown, reboot, outlet, self-test, power-setting or remote-command verbs. sources test performs one read. doctor prints fixes but never runs them. Typing mainskeeper shutdown is an unknown command (exit 2).

Local first, fleet second

Every screen answers “what does this collector see now?”. Fleet context — the site summary, open-incident count and a dashboard link — comes from the last server contact and is labelled that way.

Same truths as the dashboard

• UPS reading age and collector contact age are separate.
• “UPS estimate … est.” is never the same as “observed on battery”.
• Missing values are “Unsupported” or “Not reported”, never 0.
• History upload is shown on its own and never holds an incident open.
• Reading freshness is relative to the source’s reporting interval I (allowance g = max(30 s, I/2)): On schedule ≤ I + g · Overdue ≤ 2I + g · Stale · last known beyond — always with the absolute age and the expected interval (“On schedule · read 7 min ago · expected every 10 min”). Thresholds come from MK.freshness, never from the CLI.
• A network UPS is identified by namespace · protocol · host:port (· NUT UPS name). The same identity twice is “Already monitored by <collector> as <UPS>”; a trustworthy serial match at another identity is only a warning to confirm.
• Incident times use First evidence · Grace period started · Declared · Acknowledged · Recovered · Resolved.
• Site witnesses carry site expectations; an ordinary workstation that sleeps is “Asleep (ordinary workstation)” — no incident.

Reads by default, changes elevated

Read-only commands need no elevation. Commands that change this machine — enroll, sources add/auth/test/use/remove, config set and service actions — need sudo on macOS, Fedora and Raspberry Pi OS, and an elevated terminal (Administrator PowerShell, no sudo) on Windows. logs needs membership of the mainskeeper group, or elevation. Dashboard-managed settings are read-only here.

stdout and stderr

• stdout carries the result you asked for: the screen, or one JSON document.
• stderr carries errors, warnings, progress, spinners and the enroll wait line.
• Usage errors leave stdout empty, so pipes never receive half a document.
• In the mockups, stderr lines have a grey bar in the left gutter. The bar is not part of the output.

Colour, NO_COLOR and TTY

• Colour is on only when stdout is a TTY, TERM is not dumb, NO_COLOR is unset or empty, and --no-color is absent.
• Every state is also a glyph and a word (● on utility, ■ on battery, ▲ warning, ✗ failed, ⇡ history arriving, ▨ Unsupported), so plain output loses nothing.
• Spinners, in-place redraws and --watch need a TTY. Without one, the enroll wait prints one line per minute and --watch exits 2.

Interactive and headless

• sources auth reads a source’s secret from the terminal with echo off. Without a TTY it exits 2.
• sources use asks one yes/no question only when the source has a possible serial match to confirm. Without a TTY it then refuses (exit 1) and changes nothing.
• enroll opens the browser in a desktop session: macOS or Windows, or Linux with DISPLAY/WAYLAND_DISPLAY outside SSH.
• --headless, or no display, prints https://mainskeeper.example.net/enroll and a short code such as WDJB-MJHT.
• The device polling secret and the issued credential are never printed, logged or put in a URL.
• Other commands never prompt and never wait for input when stdin is not a TTY.

Width

• Width comes from the terminal, then COLUMNS. Without a TTY the default is 80.
• Below 100 columns (around 80), each key gets its own line and its values stack under it. Tables become one block per row.
• At 100 columns or more (around 120), keys sit in a 16-column gutter, values share a line, and tables show columns.
• Long values wrap with a hanging indent. Data is never cut off with “…”. Commands to copy always stay on one line.

Time

• Times are shown in the collector’s local zone with its abbreviation, e.g. 15:22 PDT. The header carries the full date.
• Times from another day show the weekday and date, e.g. Tue 29 Sep 13:22 PDT.
• Ages appear next to the time (“3 s ago”). Uncertain times carry ±90 s.
• History is listed by observation time, with the receipt time when it explains a delay.

Fleet context and links

• status ends with one dashboard link: the open incident first, then the site, then the collector.
• The site summary and fleet incident count come from the last server contact.
• When the server cannot be reached, it says “fleet context unavailable” with the last sync time. It never shows a stale count as current.

Secrets

• Source secrets (NUT username/password, SNMP v3 secrets, SNMP community) are set only on the collector with mainskeeper sources auth <source> (elevated: sudo, or an elevated terminal on Windows) — a hidden prompt — and kept in that platform’s local secret store (see Platforms). ESP32 probes take them on their local setup page.
• They never appear as arguments, in shell history, logs, JSON or the dashboard. Everywhere they are shown as Configured, Missing or Rejected (+ last test time).
• The collector’s enrollment identity and the device polling secret are never printed or put in a URL.
• Short enrollment codes such as WDJB-MJHT are safe to show: they work once, expire after 10 minutes and need an owner’s approval.

Wording

The CLI uses the dashboard glossary: “Contact lost — cause unknown”, “Connectivity failure confirmed by local probe”, “Last known · 15:10”, “UPS estimate … est.”, “Observed on battery”, “Received late · replayed”, “History arriving”, “No records”, “UPS communication lost”, “On schedule · Overdue · Stale · last known”, “Already monitored by bw-pi-01 as BW Office UPS”, “Possibly the same UPS as BW Rack UPS (serial match) — confirm”, “Configured — waiting for UPS role”, “Saved — monitoring starts when the UPS role is applied (managed in the dashboard)”, “Site witness”, “Asleep (ordinary workstation)”, “Configured · Missing · Rejected”, “Pending · Applied · Failed”, “Local override”, “Set locally”.

Backfill and replay

Historical backfill updates history at observation time and does not generate duplicate or obsolete notifications. Fresh evidence of an active condition remains alertable while a backlog drains. Ordinary transmission latency does not make a reading historical replay.

Replay = a record received more than 2 min after its observation time while the collector was reconnecting and draining its local buffer. Normal transmission latency (seconds) is not replay.