Notifications CLI commands

Operations

Uploads and publications run as operations. media upload, media replace and app upload wait for theirs by default; these commands are how you finish one you left running with --no-wait.

operations show <id>

screenrig operations show op_01EXAMPLEOPERATION00000

operations wait <id> [--timeout MS] [--poll-ms MS]

screenrig operations wait op_01EXAMPLEOPERATION00000

operations cancel <id>

screenrig operations cancel op_01EXAMPLEOPERATION00000

Events

The project event log records what the project did and what the fleet did. A published release appends application.published; an app that calls screenrig.emit(code) appends its own event, which is the most direct evidence that it ran on a screen.

Presence is in the log too. screen.offline is written once a screen has been offline for 60 seconds, and screen.online when it comes back; a reconnect inside those 60 seconds writes neither. screen.offline carries details.offline_since and, when the screen has been online before, details.last_online_at. screen.online carries details.last_online_at, plus details.offline_at when the screen was offline before it returned. Like every screen.* event, they are free on the listen stream, so an agent can keep events follow open to watch a fleet.

A Player's content updates arrive as screen.manifest_changed, screen.manifest_activated and screen.manifest_upgrade, whose details carry manifest_revision, state and, when present, code and attempt. A failed upgrade has error severity, and retrying, blocked and partial are warnings.

events list [--after CURSOR] [--limit N] [--type TYPE] [--source project|log] [--screen-id ID] [--playlist-id ID] [--app-id ID]

screenrig events list --limit 25
screenrig events list --type application.event --screen-id scr_SCREEN
screenrig events list --playlist-id pl_PLAYLIST
screenrig events list --source log --screen-id scr_SCREEN

events follow [--after CURSOR] [--timeout MS] [--type TYPE]

screenrig events follow

Notifications

A notification tells a person, or another system, when a screen changes state. An email notification sends each recipient an email, a webhook notification sends a signed HTTPS POST, and a Slack, Teams, PagerDuty or Telegram notification posts a message to a chat or pager. An organization has at most 50 of every channel together across its projects, and every project starts with one email to its owner when a screen has been offline for 10 minutes.

A notification watches the conditions you name:

A condition notifies once it has lasted --hold minutes (default 10), so a quick reconnect stays quiet. If it ends first, nothing is sent; if it ends after a notice went out, a resolved notice follows. crashing is sent at once. A notice is also skipped when someone acknowledges or snoozes the screen's alert during the hold, or when a mute covers the screen. --tag limits a notification to screens carrying that tag; without it, every screen counts.

Each notice has a severity. An opened notice is error for screen_offline and warning for every other condition, and a resolved notice or a test is info. --min-severity LEVEL (info, warning or error) creates no opened notice below that level, and a resolved notice follows its opened one. --severity CONDITION=LEVEL, repeatable, sets one condition's level for this notification, such as --severity not_playing=error; it counts for --min-severity. Teams and PagerDuty always show the level, email, Slack and Telegram text name it when the notification sets --min-severity or --severity, and a webhook body carries severity.

--active-hours SPEC sends opened notices only inside weekly windows, read in --timezone ZONE, which it requires. SPEC is DAYS HH:MM-HH:MM, such as "Mon-Fri 08:00-22:00"; repeat it up to 16 times. With --outside-hours hold, the default, a notice that falls due outside the hours waits for the next window and goes out then if its condition still holds, so a condition that clears first sends nothing. With drop the notice is skipped as outside_hours, which notifications deliveries lists. A resolved notice for an opened notice that was sent always goes out, crashing follows the hours like any other condition, a snooze is checked first, and notifications test ignores hours, severity and audience.

--audience FILE (inline JSON, a file, or - for stdin) chooses the screens with the rules of a campaign audience, such as {"all":[{"tag":"level2"},{"tag":"overhead"}]} for screens carrying both tags; --all-tags TAG and --any-tag TAG are the shorthands for an all and an any rule of tags, and --tag means any of the tags. --tag, --any-tag, --all-tags and --audience exclude one another.

loop_stalled, glass_blank and glass_frozen are verdicts screenRIG draws from the play reports and screenshots it receives, and they leave out what they cannot judge: a screen that is offline, whose display is off, that is under a takeover or suspended, that shows a single still or a video wall, or whose Player sends no play numbers. When screenRIG stops judging a screen it had found in one of them, the alert closes, but email, Slack, Teams and Telegram send no resolved notice, because nothing showed the screen recovering; PagerDuty still resolves its incident.

source_failed and source_stale watch the project's data sources, not its screens: a notice names the source and links its page, and --tag never matches a source.

card_data_stale watches a card, not a screen. Write a card's data with an expiry sized to its writer's schedule (card data put --ttl 30m), and when the job or agent that renews it stops, the data expires, the card is blank on every screen that shows it, and this condition tells you. The notice names the card and when its data expired, and links the page editor on a page that places it. A data source's documents are never announced here (source_stale covers them), and neither is a card no screen shows, data written with no expiry, or data that was deleted. --tag never matches a card.

reach_dropped and group_empty watch a campaign, not a screen. The notice names the campaign and the screens it reached before and now, or the empty tag or folder, and links to the campaign's calendar. A campaign belongs to the project, so --tag, --any-tag, --all-tags and --audience never limit these two; --min-severity, --severity, --active-hours and --hold apply as for any condition, and both are warning by default. --reach-drop-screens N and --reach-drop-percent P send a reach_dropped notice only for a drop of at least N screens and at least P percent of the screens the campaign reached when it was published; a drop must meet both, and without them any drop notifies. They need reach_dropped in --conditions. Each empty tag or folder of a campaign is its own notice, and notifications deliveries shows it as audience_group (tag:Lobby or folder:sfd_…). A publish that removes an empty group from the audience closes a PagerDuty incident and a webhook's alert but sends no recovery email or chat message.

Email goes to each recipient's verified address, one email per recipient for everything that falls due within about two minutes, with a link to each screen and to the notification in the dashboard. Recipients are owner, whoever owns the project when the notice sends, and the user ids of project members. A recipient with no verified address, or who has left the project, is skipped. Notification emails and screen notices are free.

Every email carries an unsubscribe link for its own recipient: the Unsubscribe button of mail apps, and a link in the footer. Following it stops that notification's emails to that one person, without signing in, and the page it opens has a Resubscribe button. The other recipients are unaffected, and the person stays in the recipients. notifications show lists who unsubscribed with unsubscribed, and notifications resubscribe mails them again. A notice with nobody left to email is skipped as no_recipients.

A webhook notification POSTs each notice as JSON, which you verify as described under Verify a delivery. With --events it also POSTs raw project events as they happen; those deliveries are metered as described under Webhooks.

A Slack, Teams, PagerDuty or Telegram notification posts one message per outage and screen, or per group of screens: the screen, what changed, since when, the project, a link to the screen, and, when an offline screen is back, its likely cause if one is known by then. A recovery message follows once the first one went out, and in PagerDuty it resolves the incident the first one opened. You give the credential once (--slack takes an incoming webhook URL, --teams the URL of a Workflows webhook, --pagerduty an Events API v2 routing key, --telegram a bot token with --telegram-chat); it is sealed, never shown again, and destination_hint shows only its masked end. A - reads it from one line of stdin so it stays out of your shell history. A failed post is retried for 24 hours, and a notification that fails for 72 hours is disabled.

When three or more screens fall into the same condition within five minutes of one another and share a network, location, model, Player version or tag, an email, Slack, Teams, PagerDuty or Telegram notification sends one notice for them instead of one per screen, and one notice says the group when its last screen recovers; each other screen's notice is skipped as grouped. A webhook still sends one notice per screen.

Reading notifications and their deliveries needs Read only access; creating, changing, testing and deleting one, rotating its secret and resubscribing a person need Manage access.

notifications create (--email RECIPIENTS | --webhook URL | --slack URL | --teams URL | --pagerduty KEY
                      | --telegram TOKEN --telegram-chat CHAT_ID) [--conditions LIST] [--events TYPES]
                     [--tag TAG... | --any-tag TAG... | --all-tags TAG... | --audience FILE] [--hold MINUTES]
                     [--min-severity LEVEL] [--severity CONDITION=LEVEL]... [--active-hours SPEC]...
                     [--timezone ZONE] [--outside-hours hold|drop] [--reach-drop-screens N] [--reach-drop-percent P]
                     [--description TEXT] [--disabled]

screenrig notifications create --email owner --conditions screen_offline,display_disconnected --tag Lobby

screenrig notifications create --webhook https://hooks.example.com/screenrig --conditions screen_offline,crashing

screenrig notifications create --slack - --conditions screen_offline,crashing < slack-url.txt

notifications list

screenrig notifications list

notifications show <id>

screenrig notifications show ntf_01EXAMPLENOTICE00000

notifications update <id> [--email RECIPIENTS | --url URL | --destination VALUE] [--telegram-chat CHAT_ID]
                          [--conditions LIST | --clear-conditions]
                          [--events TYPES | --clear-events] [--tag TAG... | --any-tag TAG... | --all-tags TAG... | --audience FILE | --all-screens]
                          [--hold MINUTES] [--min-severity LEVEL | --clear-min-severity]
                          [--severity CONDITION=LEVEL]... [--clear-severity]
                          [--active-hours SPEC]... [--timezone ZONE] [--outside-hours hold|drop] [--clear-active-hours]
                          [--reach-drop-screens N] [--reach-drop-percent P] [--clear-reach-drop]
                          [--description TEXT | --clear-description] [--enable | --disable]
                          [--snooze WHEN] [--expect-rev REVISION]

screenrig notifications update ntf_01EXAMPLENOTICE00000 --snooze 2h

notifications delete <id> [--expect-rev REVISION]

screenrig notifications delete ntf_01EXAMPLENOTICE00000

notifications rotate-secret <id> [--expect-rev REVISION]

screenrig notifications rotate-secret whk_01EXAMPLEWEBHOOK00000

notifications test <id>

screenrig notifications test ntf_01EXAMPLENOTICE00000

notifications resubscribe <id> --user USER_ID

screenrig notifications resubscribe ntf_01EXAMPLENOTICE00000 --user usr_01EXAMPLEPERSON0000

notifications deliveries <id> [--before CURSOR] [--limit N]

screenrig notifications deliveries ntf_01EXAMPLENOTICE00000 --limit 20

Verify a delivery

A screen notice's body is JSON: type (alert.opened or alert.resolved), id (the delivery id), notification_id, project_id, condition, screen (id and name), since (when the condition began), at (when it held long enough, or cleared), event_id and severity (info, warning or error: the condition's level on alert.opened, info on alert.resolved). alert.resolved for screen_offline also carries likely_cause (device_restart, app_crash, app_restart, network or platform), null while the cause is unknown. For a data source, a campaign or a card, screen names it, and a campaign notice adds reach (published and current screens) for reach_dropped or audience_group (kind tag or folder, and value) for group_empty. A raw event from --events is the same JSON object events list returns. The headers are ScreenRig-Webhook-Id (the notification id), ScreenRig-Event-Id (stable across retries: the delivery id for a notice, the event cursor for an event), and ScreenRig-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 over "<t>.<raw body>" keyed with the secret string. Compute it over the raw bytes before parsing JSON, compare in constant time, reject an old t, and deduplicate on ScreenRig-Event-Id, because delivery is at least once and unordered. Answer 2xx within 10 seconds; redirects are not followed.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body bytes (Buffer) exactly as received.
function verify(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (typeof signatureHeader !== "string" || !signatureHeader) return false;
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Alerts

An alert is one problem on one screen while it lasts. It opens when a screen enters one of the screen notification conditions (screen_offline, display_disconnected, running_hot, on_battery, storage_full, content_stuck, not_playing, loop_stalled, glass_blank or glass_frozen), whether or not a notification watches it, and resolves when the condition ends. A screen has at most one open alert per condition. A crash spike, a data source, a card and a campaign are notices, never alerts. A screen that restarts for a reboot screenRIG sent (screen reboot or a reboot schedule) opens no screen_offline or display_disconnected alert until the reboot is done or ten minutes after it was sent; a condition that still holds then opens its alert. alerts list shows what is open now.

An open alert needs attention until someone acknowledges or snoozes it, or a mute covers its screen. Acknowledging says someone is on it: the alert stays open, records who acknowledged it and when, and needs no attention until it resolves. Snoozing acknowledges until a time at most 30 days ahead, and the alert needs attention again then if it is still open. A later acknowledge or snooze replaces the earlier one. While an alert is acknowledged or snoozed, a notification's notice about it that is still in its hold is skipped.

A mute is for maintenance: it names screens, tags or both and ends at a time at most 30 days ahead. It covers a screen while the screen's id is listed or it carries a listed tag, so a screen tagged later is covered and one that loses the tag is not. A muted screen's alerts still open and resolve, marked muted, but never need attention, and every notification skips their notices. An organization has at most 50 current mutes across its projects.

counts.attention in alerts list is the number the dashboard shows beside Alerts. Opening, resolving and acknowledging an alert append screen.alert_opened, screen.alert_resolved and screen.alert_acknowledged to the project event log, and creating and ending a mute append alert_mute.created and alert_mute.deleted. They are free on the listen stream and on webhooks, as every screen.* event is. Resolved alerts stay listed for the plan's event retention. Reading alerts and mutes needs Read only access; acknowledging, snoozing, muting and unmuting need Manage access.

alerts list [--state open|resolved|all] [--screen-id ID] [--before CURSOR] [--limit N]
            [--format json|csv|xlsx|pdf] [--output FILE]

screenrig alerts list

screenrig alerts list --state all --screen-id scr_01EXAMPLESCREEN00000000

screenrig alerts list --state all --format csv --output alerts.csv

alerts show <id>

screenrig alerts show alr_01EXAMPLEALERT000000

alerts ack <id>

screenrig alerts ack alr_01EXAMPLEALERT000000

alerts snooze <id> (--for DURATION | --until TIME)

screenrig alerts snooze alr_01EXAMPLEALERT000000 --for 4h

alerts mute [--screen-id ID]... [--tag TAG]... (--for DURATION | --until TIME) [--note TEXT]

screenrig alerts mute --tag Lobby --for 2h --note "Rewiring the lobby displays"

alerts mutes

screenrig alerts mutes

alerts unmute <mute-id>

screenrig alerts unmute amt_01EXAMPLEMUTE0000000

Webhooks

A webhook sends this project's own events to an HTTPS endpoint you run as signed POSTs, so a matching event can wake an agent, a bot, or your own service. Each matching event arrives as the same JSON object events list returns. A webhook is a notification in its original form: it counts toward the organization's 50 notifications, and notifications list shows it. New work uses notifications, which also sends email and screen notices.

Each delivery attempt is free and does not count toward the organization's hourly agent request cap.

webhooks create --url URL --event-types TYPES [--description TEXT] [--disabled]
webhooks list
webhooks show <id>
webhooks update <id> [--url URL] [--event-types TYPES] [--description TEXT | --clear-description]
                     [--enable | --disable] [--expect-rev REVISION]
webhooks delete <id> [--expect-rev REVISION]
webhooks rotate-secret <id> [--expect-rev REVISION]
webhooks test <id>
webhooks deliveries <id> [--before CURSOR] [--limit N]

webhooks create answers webhook_limit_reached (exit 5) when the organization already has 50 notifications, where notifications create answers notification_limit_reached. A refused URL is webhook_url_rejected (exit 8) for both.

--url takes an https URL on port 443 or 8443 whose host resolves only to public Internet addresses, checked like notifications create; a URL that carries credentials or a # fragment is refused locally with exit 2. --event-types takes 1 to 32 comma-separated exact types, such as screen.online, or prefixes ending in .*, such as screen.*. --description is at most 200 characters. --disabled creates the webhook disabled. webhooks update --enable clears the failure state and starts at the current event, so nothing from while it was disabled is sent, and --disable fails pending deliveries with webhook_disabled. --expect-rev guards the revision (revision_conflict, exit 6).

webhooks create and webhooks rotate-secret print the signing secret once in data.secret with the warning webhook_secret_shown_once; after an interrupted or ambiguous call, rerun the identical command within 24 hours to get the same answer back. Delivery starts with the first event after the webhook is created. webhooks test queues one webhook.test delivery for this webhook only; it works on a disabled webhook, is attempted once without retries, is metered like any delivery, and is limited to 20 a minute per organization (rate_limited, exit 7). webhooks list shows this project's webhook notifications, oldest first, and a Read only credential receives each url empty with url_redacted true. webhooks deliveries reads the log newest event first, 1 to 200 rows a page (default 50), with next_cursor (whc1_…) as --before; a row's state is pending, succeeded or failed, with last_status and a fixed last_error class. Verify a delivery as described under Verify a delivery.