Device health CLI commands

Reboot a screen's device, or a fleet's devices.

screen reboot (<id>... | --tag TAG | --folder ID) [--yes] [--expires-in DURATION] [--expect-rev REVISION]

screenrig screen reboot scr_LOBBY
screenrig screen reboot scr_LOBBY --expires-in 2h
screenrig screen reboot --tag Lobby --yes
screenrig screen reboot --folder sfd_01EXAMPLEFOLDER000000000 --yes

The Player reboots the device, not just itself. A screen that is online is sent the reboot at once (state sent); an offline screen holds it queued and is sent it when it comes online before expires_at, 24 hours after the request unless --expires-in says otherwise. The answer carries reboot_id, state and expires_at. A newer reboot supersedes one still queued. screen show lists the screen's commands: a sent reboot becomes done once the device reports it booted, and screen command cancel cancels one still queued. In a fleet, each result's reboot carries the same state. A refused or failed request, and an exact replay of the same request, do not count toward the per-screen limit. From the moment a reboot is sent until the device reports it booted or ten minutes pass, the screen opens no screen_offline or display_disconnected alert; a notice for either that falls due then waits until that period ends plus its hold, and a crashing notice is skipped as planned_reboot. A condition that still holds afterwards opens normally.

Clear the caches of a screen's Player, or of a fleet's Players.

screen clear-cache (<id>... | --tag TAG | --folder ID) [--yes] [--expires-in DURATION] [--expect-rev REVISION]

screenrig screen clear-cache scr_LOBBY
screenrig screen clear-cache scr_LOBBY --expires-in 2h
screenrig screen clear-cache --tag Lobby --yes

The Player deletes its downloaded media, application packages and data caches, keeps its pairing, identity and settings, then fetches the manifest and content again; the screen can show its loading state while content refills. It reaches only a Player that declares clear_cache. A screen that is online is sent the request at once (state sent); an offline screen holds it queued and is sent it when it comes online before expires_at, 24 hours after the request unless --expires-in says otherwise. The answer carries command_id, command, state and expires_at. A Player that does not declare the capability answers 409 command_unsupported and nothing is sent; in a fleet that screen fails alone. screen show lists the command under commands and, once the Player reports, marks it done or failed with a cause and a short detail: cleared when the caches are cleared and the refetch has started, or clear_failed when a cache cannot be cleared. A sent command with no report stays sent. A newer command of the same kind supersedes one still queued, and screen command cancel cancels one still queued. In a fleet, each result's command carries the same state. A fleet (several ids, --tag or --folder) needs --yes. A refused or failed request, and an exact replay of the same request, do not count toward the per-screen limit of 2 clear-cache, restart-app and update-software requests together per 10 minutes.

Restart the application of a screen's Player, or of a fleet's Players.

screen restart-app (<id>... | --tag TAG | --folder ID) [--yes] [--expires-in DURATION] [--expect-rev REVISION]

screenrig screen restart-app scr_LOBBY
screenrig screen restart-app scr_LOBBY --expires-in 2h
screenrig screen restart-app --tag Lobby --yes

The Player restarts its application, not the device (a web Player reloads its page) and reports from the restarted process. It reaches only a Player that declares restart_app; screen reboot restarts the device. A screen that is online is sent the request at once (state sent); an offline screen holds it queued and is sent it when it comes online before expires_at, 24 hours after the request unless --expires-in says otherwise. The answer carries command_id, command, state and expires_at. A Player that does not declare the capability answers 409 command_unsupported and nothing is sent; in a fleet that screen fails alone. screen show lists the command under commands and, once the Player reports, marks it done or failed with a cause and a short detail: restarted, or restart_failed when the restart cannot start. A sent command with no report stays sent. A newer command of the same kind supersedes one still queued, and screen command cancel cancels one still queued. In a fleet, each result's command carries the same state. A fleet (several ids, --tag or --folder) needs --yes. A refused or failed request, and an exact replay of the same request, do not count toward the per-screen limit of 2 clear-cache, restart-app and update-software requests together per 10 minutes.

Update a screen's Player to the newest release, or a fleet's Players.

screen update-software (<id>... | --tag TAG | --folder ID) [--yes] [--expires-in DURATION] [--expect-rev REVISION]

screenrig screen update-software scr_LOBBY
screenrig screen update-software scr_LOBBY --expires-in 2h
screenrig screen update-software --tag Lobby --yes

The Player checks for the newest Player release now and installs it where its platform lets the Player update itself; a web Player updates its service worker, then reloads. It reaches only a Player that declares update: a Player installed from a store or managed by a device manager updates through that channel. A screen that is online is sent the request at once (state sent); an offline screen holds it queued and is sent it when it comes online before expires_at, 24 hours after the request unless --expires-in says otherwise. The answer carries command_id, command, state and expires_at. A Player that does not declare the capability answers 409 command_unsupported and nothing is sent; in a fleet that screen fails alone. screen show lists the command under commands and, once the Player reports, marks it done or failed with a cause and a short detail: up_to_date when the newest release already runs, updated once the new version has started, or, when it failed, update_check_failed, download_failed, install_failed or no_update_channel. A sent command with no report stays sent. A newer command of the same kind supersedes one still queued, and screen command cancel cancels one still queued. In a fleet, each result's command carries the same state. A fleet (several ids, --tag or --folder) needs --yes. A refused or failed request, and an exact replay of the same request, do not count toward the per-screen limit of 2 clear-cache, restart-app and update-software requests together per 10 minutes.

Cancel a command that is still queued for an offline screen.

screen command cancel <id> <command_id> [--expect-rev REVISION]

screenrig screen command cancel scr_01EXAMPLESCREEN00000000 rbt_01EXAMPLEREBOOT00000000

It cancels a reboot, reload, clear_cache, restart_app or update that waits for an offline screen, so it is never sent. Only a queued command can be cancelled. One that was already sent (sent or done) answers 409 resource_conflict with "The command was already sent.", one that is no longer queued (expired, cancelled, or superseded) answers 409 resource_conflict with "The command is no longer queued.", and an id the screen does not list answers 404 not_found. The answer is the screen with the command cancelled, and the screen revision does not change.

Turn a screen's display, or a fleet's displays, on or off now, or clear that override.

screen display [set] (<id>... | --tag TAG | --folder ID) --power on|off [--until TIME | --for DURATION] [--expect-rev REVISION]
screen display clear (<id>... | --tag TAG | --folder ID) [--expect-rev REVISION]

screenrig screen display scr_LOBBY --power off --for 2h
screenrig screen display --tag Lobby --power on
screenrig screen display scr_A scr_B --power off --for 8h
screenrig screen display clear --tag Lobby

screen display ID is short for screen display set ID; clear takes no --power, --until or --for. screen display is a manual override of the display schedule. Without --until or --for it ends at the schedule's next boundary; a later display-schedule or timezone change moves that end to the new boundary. With no boundary in the next eight days, for example with no enabled schedule, it holds until screen display clear or a replacement. screen display clear ends the override, so the display schedule applies again; without one, the display is on.

Saving an override does not wait for the Player. display.override_status compares a newer display report with it: matches, mismatch, pending, stale or unknown; matches describes the report, not that the command ran. The warning display_power_mismatch names a fresh report that differs and display_power_unconfirmed says a newer usable report is needed, so check screen show before taking a screenshot. display_scrim_only means the Player controls only a black overlay: on removes it and sends no hardware wake. A screen in a protected folder refuses a display change (protected_target).

Show, set, or clear when a screen's display is on.

screen display-schedule show <id>
screen display-schedule set (<id>... | --tag TAG | --folder ID) --file FILE [--expect-rev REVISION]
screen display-schedule clear (<id>... | --tag TAG | --folder ID) [--expect-rev REVISION]

screenrig screen display-schedule set scr_LOBBY --file hours.json
screenrig screen display-schedule set --tag Cafe --file hours.json

A display schedule is {enabled, windows}, both required, and windows lists 1 to 16 windows when the display is on, in the screen timezone; outside every window the display goes to standby. The Player evaluates it on the device, so it keeps working offline. A window whose end is at or before its start crosses midnight, and a window without start and end covers the whole day. enabled: false keeps the windows and leaves the display on. display-schedule show answers display_schedule (null when there is none) and the screen's display state. Its saved output can be edited and sent back with set --file. A screen in a protected folder refuses a change to its display schedule (protected_target).

{"enabled": true, "windows": [{"days": ["mon", "tue", "wed", "thu", "fri"], "start": "07:00", "end": "19:00"}, {"days": ["sat"]}]}

screen show --human prints Display: with the requested power, its source (manual override, display schedule, or default) and until when in the screen timezone, the schedule windows, and the power the Player reported, marked stale after 35 minutes without a report.

Set a screen's volume, or mute it, on one screen or a fleet.

screen volume (<id>... | --tag TAG) [--level 0-100] [--mute | --unmute] [--expect-rev REVISION]

screenrig screen volume scr_LOBBY --level 40
screenrig screen volume scr_LOBBY --mute
screenrig screen volume scr_LOBBY --unmute
screenrig screen volume --tag Lobby --level 25 --unmute

A screen has one volume: a level from 0 to 100 and a mute. Muting keeps the level, so unmuting restores it. A screen that is online applies the change at once; an offline screen applies the latest request when it comes back, and a newer request replaces an earlier one. A change made later in the Player's own settings menu wins until the next screen volume, and changing the level there clears the mute. screen show reports volume with the latest requested change and, as reported, the level and muted the Player reached and hardware: true when the level reaches the device or panel output, false when it is the Player's own gain; stale turns true after 35 minutes without a report. Only a Player that declares the volume capability applies it: any other screen answers 409 volume_unsupported (exit code 5) and nothing is recorded. An archived screen answers screen_archived and a screen still waiting to pair answers resource_conflict. A screen in a protected folder refuses the change (protected_target), and in a fleet one protected screen refuses the whole request. The dashboard's screen page has the same Volume control.

Darken a screen's glass after a time without use, or turn that off.

screen display-idle <id> --after SECONDS --wake WAKE [--expect-rev REVISION]
screen display-idle <id> --off [--expect-rev REVISION]

screenrig screen display-idle scr_LOBBY --after 300 --wake touch
screenrig screen display-idle scr_LOBBY --after 600 --wake touch,presence --expect-rev 4
screenrig screen display-idle scr_LOBBY --off

The glass goes dark after --after seconds without a touch or key or, when --wake lists presence, anybody in front of the screen. While it is dark the Player parks playback, with no plays and no ads, and reports display power off; a wake event lights the glass at once and playback resumes, and the touch that wakes a dark glass is not passed to the page. A display schedule or override that holds the panel off wins, and so does an application that holds device.display while its page is on glass. Only display.idle changes. A Player applies it when screen show lists display_power.idle in its host capabilities; the setting is stored either way, and screen show lists it as Display idle. Propose access cannot change it (insufficient_access), and a screen in a protected folder refuses it (protected_target).

Set whether a screen's brightness follows the device's light sensor.

screen brightness <id> --mode auto|fixed [--expect-rev REVISION]

screenrig screen brightness scr_LOBBY --mode auto
screenrig screen brightness scr_LOBBY --mode fixed --expect-rev 4

Only display.brightness changes. A Player applies auto when screen show lists brightness.auto in its host capabilities, which a device declares only with a light sensor; an application that sets the display's brightness wins while its page shows. The setting is stored either way, and screen show lists it as Display brightness. The access rules of screen display-idle apply.

Set the video mode a screen's Player puts on its output, or clear it.

screen display-output <id> (--mode MODE | --clear) [--expect-rev REVISION]

screenrig screen display-output scr_LOBBY --mode 3840x2160x60p
screenrig screen display-output scr_LOBBY --mode auto --expect-rev 4
screenrig screen display-output scr_LOBBY --clear

screen show lists the modes the Player can set now, under Output modes the Player can set, and the mode in force. Once the Player has reported them, a mode outside that list is invalid_request, so pick one it lists. Only display.output changes. A Player applies it when screen show lists display_output.mode in its host capabilities, which a BrightSign player declares; any other mode than auto on another Player answers display_output_unsupported, and clearing always works. The Player applies a mode once, may restart to do it, and reports the mode it reached. The access rules of screen display-idle apply.

Have a screen's Player take the TV's HDMI input over CEC, or stop.

screen display-cec <id> (--on | --off | --clear) [--expect-rev REVISION]

screenrig screen display-cec scr_LOBBY --on
screenrig screen display-cec scr_LOBBY --off --expect-rev 4
screenrig screen display-cec scr_LOBBY --clear

Only display.cec changes. A Player applies it when screen show lists display_power.cec_active_source in its host capabilities, which a BrightSign player declares; --on on another Player answers display_cec_unsupported, while --off and --clear always work. The Player sends nothing while a display schedule or override holds the display off, and a CEC failure never affects playback. screen show lists the setting as Display CEC. The access rules of screen display-idle apply.

Pin a screen's Player to the screen, or release it.

screen kiosk-lock <id> (--on | --off) [--expect-rev REVISION]

screenrig screen kiosk-lock scr_LOBBY --on
screenrig screen kiosk-lock scr_LOBBY --off --expect-rev 4

--on uses Android screen pinning: the person at the screen confirms the first time, and the status bar, home and recents are blocked while the Player is pinned. The operator settings panel can leave the lock until the next manifest or restart applies it again. A Player applies it when screen show lists kiosk_lock in its host capabilities; the setting is stored either way, and screen show lists Kiosk lock while it is on. Propose access cannot change it (insufficient_access).

Show, set, or clear when the backend reboots a screen's device.

screen reboot-schedule show <id>
screen reboot-schedule set (<id>... | --tag TAG | --folder ID) (--window SPEC... | --file FILE) [--disabled] [--expect-rev REVISION]
screen reboot-schedule clear (<id>... | --tag TAG | --folder ID) [--expect-rev REVISION]

screenrig screen reboot-schedule set scr_LOBBY --window "Mon-Sun 04:00-04:30"
screenrig screen reboot-schedule set --tag Cafe --window "Mon-Fri 04:00-04:30" --window "Sat,Sun 05:00-06:00"
screenrig screen reboot-schedule set scr_LOBBY --file reboots.json --expect-rev 4
screenrig screen reboot-schedule set --folder sfd_01EXAMPLEFOLDER000000000 --window "Mon-Sun 04:00-04:30"

At the start of each window, in the screen timezone, screenRIG issues the same reboot as screen reboot, so "Mon-Sun 04:00-04:30" reboots the screen at 04:00 local time every day. commands in screen show lists it with source schedule, and screen show and reboot-schedule show print next_reboot_at. A window whose end is at or before its start crosses midnight, and a window without times covers the whole day. The saved output of reboot-schedule show can be edited and sent back with set --file:

{"enabled": true, "windows": [{"days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"], "start": "04:00", "end": "04:30"}]}

An online screen is sent the reboot at once. An offline screen keeps it queued only until its window ends, so a reboot never lands outside the window: a screen that comes back after it gets none. A start inside a spring-forward gap fires at the first valid minute of the window, and a fall-back repeat fires once per window per local date. A scheduled reboot never replaces one a person asked for that still waits for the screen; the occurrence is skipped with screen.reboot_skipped (reboot_pending). The screen needs a Player that declares reboot; a screen that loses reboot later skips each window and keeps its schedule. Changing the timezone cancels the scheduled reboots still waiting and moves next_reboot_at to the new zone. A reboot a schedule sent raises no offline alert, as under screen reboot. screen.reboot_schedule_changed records each set or clear. A file is {enabled, windows}, both required. Reboot schedules are in every plan. In a fleet, each result is that screen's own: reboot_unsupported for a screen whose Player cannot reboot.

Read a screen's daily availability over UTC days.

screen uptime <id> [--day-from YYYY-MM-DD] [--day-to YYYY-MM-DD] [--format json|csv|xlsx|pdf] [--output FILE]

screenrig screen uptime scr_01EXAMPLESCREEN00000000
screenrig screen uptime scr_01EXAMPLESCREEN00000000 --day-from 2026-09-01 --day-to 2026-09-30
screenrig screen uptime scr_01EXAMPLESCREEN00000000 --format xlsx --output uptime.xlsx

data.items lists one row per UTC day with a recorded state, oldest first: online_s, offline_s, availability (online over recorded time; null when nothing was recorded), coverage (the share of the day with a recorded state), intervals, and live for a day that includes the open interval up to now. Time with no recorded state lowers coverage and is never downtime. Days with nothing recorded have no row.

List a screen's online and offline transitions, newest first.

screen presence <id> [--since TIME] [--until TIME]

screenrig screen presence scr_01EXAMPLESCREEN00000000 --since 7d
screenrig screen presence scr_01EXAMPLESCREEN00000000 --since 2026-09-01T00:00:00Z --until 2026-09-08T00:00:00Z

data.items carries at, state, and detected_on_reconnect on an offline the server noticed only when the screen reconnected (at is then when its presence lease ended). The CLI follows next_cursor to the end and answers every transition with next_cursor null, so narrow a long range with --since.

List the health a screen reported over time, each report or one summary per hour.

screen health-history <id> [--from TIME] [--to TIME] [--resolution raw|hour] [--format json|csv|xlsx|pdf] [--output FILE]

screenrig screen health-history scr_01EXAMPLESCREEN00000000 --from 6h
screenrig screen health-history scr_01EXAMPLESCREEN00000000 --from 30d --resolution hour
screenrig screen health-history scr_01EXAMPLESCREEN00000000 --from 30d --resolution hour --format csv --output health.csv

raw answers data.samples, each accepted report shaped like the health of screen show without stale. hour answers data.hours, one summary per UTC hour: reports, peak and average temperature, peak load and memory ratio, weakest Wi-Fi signal, display_disconnected, and peak crash and renderer-restart counts. The CLI follows next_cursor to the end, so narrow a long raw range or use --resolution hour. Raw reports arrive within seconds and hourly summaries within about 5 minutes.

Check whether a playlist fits the storage a screen's Player last reported, before the playlist is assigned.

screen storage-forecast <id> --playlist-id ID [--playlist-rev REVISION]

screenrig screen storage-forecast scr_01EXAMPLESCREEN00000000 --playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen storage-forecast scr_01EXAMPLESCREEN00000000 --playlist-id pl_01EXAMPLEPLAYLIST000000 --playlist-rev 7

It writes nothing: no assignment, no screen revision, no event. Read only access is enough, and a screen takes at most 30 checks a minute. data.fit is fits, partial (some pages are left out), none_fit (nothing loads) or unknown (the screen has never reported storage, or the playlist's content is not ready). data.excluded_page_count counts the pages left out, data.required_bytes is what the whole playlist needs, data.capacity_bytes what the Player reported it may use, data.basis is reported_capacity and data.received_at is when the Player reported. With fit unknown the byte counts and received_at are null. A report older than 24 hours is marked stale but still used. When the playlist does not fit, the answer carries a storage_full warning: free storage on the device that runs the Player, then check again. Cache and storage explains the plan. A saved assignment does not confirm playback.