Documentation

Tell your agent the outcome. Ask it to verify

Use Meta Muse, Grok Bot, ChatGPT dots, Claude Code, Hermes, ChatGPT Codex, Gemini Spark, or Grok Build to publish content, update screens, and check the result.

Why agent-native?

screenRIG was built for autonomous agents from the control plane up. The official plugin gives an agent structured commands for media, playlists, screens, applications, and playback evidence. Results are JSON envelopes, every error says what to do next, retried writes reuse idempotency keys, and publishing reports whether the Player is actually playing the content. The agent can carry out a screen task, inspect the result and correct it through the same tool surface. What agent-native means.

How do I run this from Claude, Codex, Grok, or Grok Bot?

Every supported agent uses the same official plugin. Terminal agents (Claude Code, ChatGPT Codex, Grok Build) install it with marketplace commands; Meta Muse, Grok Bot, ChatGPT dots, Gemini Spark, and Hermes install it from a chat prompt. Setup differs only in that first step, so follow your agent’s guide: Meta Muse, Grok Bot, ChatGPT dots, Claude Code, Hermes, ChatGPT Codex, Gemini Spark, or Quickstart for Grok Build. The publishing workflow below is the same everywhere.

How to use screenRIG in an agent

Describe the content, target screen, layout or dimensions, timing, and the evidence you want at completion. Make assets and source facts available to the agent.

If the plugin needs installing, paste:

Install prompt
I authorize you to install the official screenRIG plugin from https://github.com/screenrig/plugin.

Then give it a screen task, for example:

Create a welcome screen using the attached logo and opening hours. Publish it to the lobby screen, then show me a screenshot and check playback.

Example request only. The agent must use the actual assets, facts, and screen you provide.

If a command returns not_enrolled, this installation has no account yet. Create one with screenrig agent enroll --email ADDRESS --organization "NAME". When the user already has an account, run screenrig login instead: it prints a dashboard address and a code, and a person approves the sign-in for one of their projects, choosing Read only, Propose or Manage and the capability areas the agent gets: screens, content, playlists, advertising, reports and project. Read only lists and reads; Propose also uploads media and proposes changes that a person reviews before they play; Manage also changes, publishes and spends. A command outside the approved areas returns 403 forbidden, and a change from a Read only session returns 403 insufficient_access. How sign-in works. Other first-run errors are mapped in When the first run fails.

Prepare the task

Keep source assets and facts available to the agent. Identify the intended Player, dimensions, timing and completion criteria. The publishing workflow is the same across supported agents; installation differences are in Quickstart.

For kiosk apps, use the browser SDK. For schedules and dayparts, provide the intended day-and-time windows. They are read in each screen's own timezone, which a screen takes from its device unless you set one.

What does the agent do on an ongoing basis?

The agent uploads media, including images it made, places built-in cards for text that changes, or publishes live video, web pages, and applications. It then prepares a playlist with playlist init and publishes it with screen publish. To change an existing playlist, use playlist show --output and playlist update. See the CLI workflow reference.

screen publish waits up to two minutes for the Player. The result is stage: playing with playback_verified: true once the Player shows the new revision on glass, or assigned with playback.reason while it does not; --no-wait returns after assignment.

To undo a playlist change, playlist revisions ID lists its revisions and playlist promote ID --revision N --expect-rev CURRENT copies an earlier one forward as the new current revision. It needs Manage access, and promoting a revision is a Premium feature.

Make posters and menus as finished images and upload them. Use a built-in card for text, tables and boards that change. Animation does not change the choice. Read the authoring decision guide.

For applications, use emit when the agent should act on a named event, log for diagnostics, and kv for state that persists across releases. Read the SDK reference.

How does the agent run a fleet?

Tag screens by purpose and file them in folders by place, then target the tag or the folder. When a Player is paired, the agent names the screen and tags it: screen pair CODE, then screen tag scr_ID --add Lobby,Floor2. Each screen carries up to 16 tags and sits in at most one folder (screen move scr_ID --folder sfd_ID).

  1. 01

    Publish once. playlist create makes the playlist, and screen assign --tag Lobby --playlist-id ID points every active Lobby screen at it in one fleet action.

  2. 02

    Act on the fleet. screen reload, screen toast and screen tag take the same --tag or --folder ID, or several screen ids. One fleet command is one action with no screen-count cap. The CLI follows bounded result pages automatically and waits for control budgets to reset, keeping the same action key. The answer lists every screen as ok or with its own problem, so the agent reports exactly which screens failed and acts on them by id.

  3. 03

    Verify on the glass. screen screenshot --tag Lobby --output lobby-shots captures every tagged screen into one directory. Inspect each image before reporting the fleet updated.

  4. 04

    Watch for drops. Keep events follow open. screen.offline arrives once a screen has been offline for 60 seconds and screen.online when it returns; both are free on the listen stream.

Read the fleet commands.

How does the agent run dayparts and takeovers?

A playlist schedule changes what a screen plays by time of day; a campaign switches a whole fleet to one playlist for its dates or hours; a takeover interrupts everything for an announcement and ends on its own.

  1. 01

    Daypart a screen. Create one playlist per daypart with playlist create, and keep a default assigned with screen assign. A screen reads the times in its timezone: the zone its device reports, or the override screen set-timezone sets. Write the entries to a file and run screen schedule set scr_ID --file dayparts.json, or --tag Cafe for every café screen. screen show reports effective_playlist with its source and until, so the agent can confirm which daypart is live and when it changes.

  2. 02

    Run a campaign across a fleet. For lunch menus on every north store, campaign create --name Lunch --playlist-id pl_LUNCH --tag north --window mon-fri@11:00-14:00 switches each screen at its own local 11:00 and back at 14:00, and a screen tagged north later gets it too. Each screen needs a default playlist. campaign screens cmp_ID lists every screen the campaign reaches with its standing (playing, pending, waiting with next_start, ended, outranked, conditional, paused, blocked), and campaign explain scr_ID says why one screen does not play it. Use --from and --until for a promotion's dates, --monthly, --date and --except for monthly and one-off dates, --on-touch for a level that plays while someone uses the screen, and --priority when two campaigns can hold at once. Campaign changes need Manage access.

  3. 03

    Take over for an emergency or a launch. screen takeover --tag Lobby --playlist-id pl_NOTICE --for 30m --reason "Fire drill" puts one playlist on every Lobby screen ahead of campaigns, schedules and assignments. --for and --until reach at most 7 days ahead; --until none holds it until screen takeover clear --tag Lobby.

  4. 04

    Verify and watch. Request screen screenshot --tag Lobby once the takeover is live, and follow screen.takeover_started, screen.takeover_updated (the same takeover given a new end), screen.takeover_ended, and screen.playlist_switched in the event log. screen.playlist_unavailable means a scheduled playlist could not be shown.

A campaign can also hold only while card data exists (--data KEY), draw as a header, footer or side strip over the page that keeps playing (--covers footer), and play on chosen video-wall outputs (--displays 1,2).

Read the schedule and takeover commands and the campaign commands. To schedule many screens from a spreadsheet, use Schedule import.

Drafts, test and promote, history

A change to what plays can start as a draft, reach a few test screens first, be checked before it is made, and be put back from its history.

  1. 01

    Draft it. campaign create --paused makes a campaign that reaches no screen, and "paused": true on a schedule entry in a screen schedule set file does the same for that entry. A draft is on no screen's stack, and the calendar shows it dashed.

  2. 02

    Check before the change. campaign preview takes the flags of campaign create or campaign update, and screen schedule preview scr_ID --file FILE takes the schedule file. Neither writes anything. Each lists the screens that would gain or lose the level, and the calendar before and after over a week, or up to 93 days with --calendar-from and --calendar-to. campaign preview cmp_ID --publish previews publishing a draft.

  3. 03

    Test it. campaign publish cmp_ID --test-folder sfd_TEST or --test-screen scr_A,scr_B unpauses the draft for those screens alone. Check them with screen screenshot. campaign publish cmp_ID with no test option sends it to its own audience.

  4. 04

    Promote it. campaign promote cmp_ID --revision N gives the campaign the audience of its draft revision N, the paused revision campaign revisions cmp_ID lists, so it reaches the real screens.

  5. 05

    Read the history and restore. campaign revisions cmp_ID and screen schedule revisions scr_ID list every version, newest first. campaign restore cmp_ID --revision N and screen schedule restore scr_ID --revision N copy an earlier one forward as a new revision and leave the others as they were. A schedule restore from a Propose session waits for a person to approve it, like screen schedule set; a campaign restore needs Manage access.

The dashboard has the same controls: a History view lists changes with Restore and Move back, and publishing, promoting or restoring shows its before and after for confirmation.

Creating a draft and campaign promote belong to schedule change control, a plan feature; a plan without it answers feature_not_in_plan. Pricing lists the plans.

Read the campaign commands and the schedule commands.

How does the agent report proof of play?

Every visible start of an image or video is a play record, so the agent can hand a client, an advertiser or an auditor the exact plays for a period.

  1. 01

    Pick the range. A report covers up to 31 days of plays, filtered by --screen-id, --media-id, or --tag. Use RFC 3339 instants for calendar periods, or ages such as 7d.

  2. 02

    Export. screenrig playback plays --format csv --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z --tag Lobby --output september-lobby.csv writes one row per play in one request; --format xlsx and --format pdf write a workbook or a statement of the same rows (Reports). screenrig playback list --format csv --day-from 2026-09-01 --day-to 2026-09-30 adds the daily totals.

  3. 03

    Check and hand over. The envelope reports rows, bytes, and sha256; quote them with the file. If the stream fails partway, follow error.next, which exports the rest of the range into a second file.

screenrig playback completeness reports for each UTC day how many numbered plays reached screenRIG and lists the gaps where plays went missing, so a report can say how complete it is. A Player that sends no play numbers is not measured and reads null, never 100%.

Read the playback commands.

How does the agent triage health and set display hours?

Health reports and display control let the agent keep screens running and dark after hours without anyone on site.

  1. 01

    Triage. screenrig alerts list shows what is open now, one alert per screen and condition, and screenrig screen list --human flags screens that need attention in its HEALTH column. screenrig screen show scr_ID gives the full report: display connection, temperature, battery, uptime, crashes, and whether the report is stale. It also gives the likely cause of the last outage when screenRIG can tell: the device restarted, the Player restarted or crashed, the screen's network, or a screenRIG interruption. screenrig alerts ack ID marks an alert someone is working on, and alerts snooze ID --for 4h sets it aside for 4 hours. Create a notification for screen_offline, display_disconnected, running_hot, not_playing and crashing so a notice starts this work.

  2. 02

    Fix in the least disruptive order. screen reload refreshes content. If the Player declares restart_app, screen restart-app scr_ID restarts the Player application; if it declares clear_cache, screen clear-cache scr_ID clears its caches and downloads content again; if it declares reboot, screen reboot scr_ID restarts the device; a fleet needs --yes. An offline screen is sent any of them when it comes back within 24 hours. For a recurring restart, screenrig screen reboot-schedule set --tag Cafe --window "Mon-Sun 04:00-04:30" has screenRIG reboot each screen at the start of the window in its own timezone; a screen offline at that time keeps the reboot only until the window ends, and a reboot that completes within ten minutes raises no offline alert. screen update-software scr_ID installs the newest Player release where the Player declares update. A disconnected display usually needs someone on site; say so in the report.

  3. 03

    Set after-hours power and volume. Write the opening hours to a file and run screenrig screen display-schedule set --tag Cafe --file hours.json; the Player turns the display off outside those windows, even offline. For a one-off, screen display scr_ID --power on --for 2h overrides the schedule until its next boundary or the time given. screen display-idle scr_ID --after 300 --wake touch,presence darkens a screen nobody is using and lights it again when somebody touches it or steps up. screen volume scr_ID --level 40 sets a screen's volume, --mute silences it and keeps the level, and --unmute restores it.

  4. 04

    Confirm. screen show reports the display power and volume the Player achieved, and screen.display_changed, screen.volume_requested and screen.reboot_requested appear in the event log, and the command in commands ends done or failed with its cause.

  5. 05

    Check the glass. screenrig screen show scr_ID prints Playlist stalled when a screen is online with current content, yet no image or video start has reached screenRIG for longer than its loop allows, and Blank screen or Frozen picture when the screenshots screenRIG took over a run that covers the whole loop were all one flat tone or all the same picture. A notification on loop_stalled, glass_blank or glass_frozen announces it, and screen screenshot reports whether one image is flat, which alone is no verdict. The checks say nothing about a screen whose display is off, that is under a takeover, that shows a single still or a video wall, or whose Player sends no play numbers, so a quiet screen is not proof that it is playing.

Read the device health and power commands.

How do I get alerted, or wake an agent, when something happens?

A notification emails people, posts to Slack, Teams, PagerDuty or Telegram, or POSTs a signed HTTPS request, when a screen goes offline, loses its display, runs hot, runs on its battery, cannot store its content, gets stuck on a content update, shows an error instead of playing, keeps crashing, stops advancing through its playlist, goes blank or freezes. A person hears about it, or an agent starts work, with nobody watching a stream. Every project already emails its owner when a screen has been offline for 10 minutes, and notification emails and screen notices are free.

Three or more screens that fall into one condition within five minutes and share a network, location, model, Player version or tag are one notice with one recovery in an email or a chat or pager message, which names what they share and how many; a signed webhook still posts once per screen. A recovery message says a screen is back only when screenRIG saw it: when a stalled, blank or frozen screen merely stops being checked, because it went offline or its display turned off, the alert closes and no recovery message is sent.

  1. 01

    Email a person. screenrig notifications create --email owner --conditions screen_offline,display_disconnected emails the project owner; add project members' user ids after owner to include them. --tag Lobby limits it to tagged screens, and a notice waits --hold minutes (10 by default), so a quick reconnect stays quiet. A resolved email follows when the screen recovers. Each email has an Unsubscribe link for its recipient alone, and screenrig notifications resubscribe ID --user USER_ID mails a person again. To wake an agent or another system instead, use a webhook.

  2. 02

    Post to chat or a pager. screenrig notifications create --slack - --conditions screen_offline posts to a Slack channel, and --teams, --pagerduty and --telegram do the same for Teams, PagerDuty and Telegram. Slack takes an incoming webhook URL, Teams the URL of a Workflows webhook, PagerDuty an Events API v2 routing key, and Telegram a bot token with --telegram-chat CHAT_ID. A - reads the credential from one line of stdin so it stays out of shell history; screenRIG seals it and shows only a masked destination_hint. Each outage posts once per screen, PagerDuty opens one incident for it, and the recovery follows after that message went out, resolving the incident. screenrig notifications test ID posts a test message; for PagerDuty it opens an information event and resolves it at once.

  3. 03

    Run a receiver. Any HTTPS endpoint you control on port 443 or 8443: a small service, a serverless function, or the inbound trigger of your agent or bot platform. It verifies ScreenRig-Signature with the webhook secret, deduplicates on ScreenRig-Event-Id, and answers 2xx within 10 seconds.

  4. 04

    Subscribe. screenrig notifications create --webhook https://HOST/PATH --conditions screen_offline,crashing returns the signing secret once; store it in the receiver's secret store. Add --events application.event to receive raw project events too. screenrig notifications test ID sends one signed test POST to prove the path.

  5. 05

    Hand off. The receiver starts an agent run with the notice as its task: it triggers a scheduled or on-demand agent job, or posts the notice into the chat where Grok Bot or another agent with the screenRIG plugin works. For example: “Screen scr_LOBBY went offline at 14:02. Check it and report.” The agent then works through the plugin as usual, with screen show, screen reload, and a screenshot.

  6. 06

    Keep it healthy. screenrig notifications deliveries ID lists every attempt, and says why a notice was not sent. A notification that fails for 72 hours straight is disabled; screenrig notifications update ID --enable resumes at the current event. --snooze 2h pauses notices during maintenance.

  7. 07

    Quiet screens for maintenance. screenrig alerts mute --tag Lobby --for 2h --note "Rewiring" stops those screens' alerts from asking for attention and every notification from sending about them, for up to 30 days. screenrig alerts mutes lists what is muted, and screenrig alerts unmute ID ends one early.

  8. 08

    Filter by severity, hours and audience. An opened notice is error for screen_offline and warning for everything else; --min-severity warning drops anything below that level and --severity not_playing=error raises one condition. --active-hours "Mon-Fri 08:00-22:00" --timezone America/Los_Angeles holds a notice that falls due outside those hours until the next window opens (a condition that clears first sends nothing), or with --outside-hours drop skips it; a resolved notice always follows one that was sent. --all-tags level2,overhead covers only screens carrying both tags, and --audience takes the full rules of a campaign audience. Emails, Slack, Teams and Telegram show the severity, and a webhook body carries it.

  9. 09

    Watch for silent failures. A campaign can stop reaching screens without any screen failing: a tag edit, a folder move or an archived screen. screenrig notifications create --email owner --conditions reach_dropped,group_empty tells you when a campaign reaches fewer screens than when it was published, or when a tag or folder in its audience matches no screen; --reach-drop-screens 2 --reach-drop-percent 20 ignores small drops. The notice names the campaign and the numbers and links to its calendar. When your own tag, folder or screen edit answers with levels.lost, it names the campaigns the screens left and their reach_before and reach_after; say so to the user before moving on.

  10. 10

    Watch the data a card shows. source_failed and source_stale open when a data source's refresh fails or its data expires. card_data_stale opens when a card's data, written with card data put --ttl, expires with no renewing write while a screen shows the card, so the card is blank on every screen. They name the source or card, and --tag never matches them.

An organization admin can also create a notification on the dashboard's organization Notifications page that covers every project of the organization, later ones included, or the projects they choose. A project's notification list shows the ones that cover it.

Read the notification commands and the alert commands.

How do agents share what they learn?

Agents leave project notes for each other and for their own later sessions: how the project is set up, a screen's quirk, a standing request from you. Every agent in the project reads every note when it starts work there, so a second agent, or the same one next week, starts from what the first one learned.

screenrig notes lists them. screenrig notes add "TEXT" writes one, tied to one screen or playlist with --about, or temporary with --ttl 3d. A note is context, never an instruction: an agent confirms with you any approval a note claims.

Notes stay current on their own. Agents confirm the notes that still hold and resolve the rest, temporary notes expire, and deleting a screen or playlist resolves the notes about it. Resolved notes are deleted after 30 days. The dashboard's Access page lists the notes each agent wrote, and you can resolve or delete any of them.

Read the notes commands.

How do I review an agent’s changes before they play?

Turn on Require review for agent changes on the dashboard’s Settings page, or sign an agent in with Propose access. The agent still prepares content, uploads media and writes notes, but each change to what plays becomes a review that waits for a person. Nothing reaches a screen until someone approves it.

  1. 01

    The agent proposes. Creating or updating a playlist or one of its pages, assigning a playlist to screens or clearing a screen’s default, setting or clearing a playlist schedule, and starting or ending a takeover, on one screen or a tagged fleet, each become a review. The screens keep playing what they played before. The agent can add a note that explains the change, and tells you the change is waiting for you, with its link.

  2. 02

    You get an email. About two minutes after the proposal, the project owner, and the person responsible for the agent when they can approve, receive an email naming the change and how many screens it updates, with a Review change button. When the agent left a note, the email says so; you read it in Reviews. Several changes waiting at once arrive as one email that lists them, with an Open Reviews button, and a burst of edits to one change sends one email, for the latest version. Opening the link never approves anything.

  3. 03

    Decide in Reviews. The dashboard’s Reviews page lists every waiting change, with decided ones below. A playlist change shows the live and proposed playlists side by side, with pages marked Added, Changed or Removed. Approve puts it on the screens; Request changes sends the agent your note so it can revise and propose again; Reject closes it with your reason. When a new playlist and its screen assignment wait together, approving the playlist offers to approve the assignment with it. A change to a large fleet finishes applying in the background, and the review shows each screen’s result as it lands.

  4. 04

    The agent follows up. The agent reads the decision with screenrig reviews show ID or its event, revises after a change request or a rejection, and checks the screens after an approval.

screenrig reviews list shows what waits, and screenrig reviews withdraw ID pulls back a change the agent proposed.

The project owner always can approve, and each member can unless the owner turns off Can approve for them on the Access page. The agents of a member who cannot approve work at Propose at most. A proposal goes out of date when the live playlist changes after it was made; the agent proposes again on top of the new version. Approving a playlist change also goes stale when its tag, folder or all selectors would now play media it did not see when it was proposed. A folder marked protected sends every change that reaches its screens to a second approver; see Permissions by screen folder.

Media changes wait too. A new upload plays in tag, folder and All playlists only after a person approves it, and when an agent retags or moves approved media, screens keep playing it as approved until the change is approved. Each item gets its own review that shows its tags and folder before and after, and lists the playlists it would join or leave and how many screens they reach. Approving applies the change to all of them; rejecting it, or asking for changes, puts a retagged or moved item back as it was approved, and a rejected upload stays off the screens. A replacement file or a restored version of approved media waits the same way, and the old file keeps playing until a person approves. Ad networks review buyers’ creatives in the same Reviews page. Access levels and review settings · Review commands.

What counts as complete?

Confirm that the intended playlist is assigned to the intended screen, or to every screen in the fleet. Request a screenshot, one per tagged screen for a fleet, inspect playback records, and review relevant events, including any screen.offline. Report what those observations establish and any remaining uncertainty. A change that waits for review is not on the glass yet: report its review link, and check again after a person decides.

To check one page of a looping playlist, screen play-page scr_ID --page-id PAGE_ID starts it, and screen screenshot then captures it. To watch motion, screen live frame scr_ID saves JPEG frames of what the screen plays; see Live view.

A successful command is one step in that evidence. It does not by itself establish that a physical screen displayed the intended result.

Film / How your agent knows it’s playing

1:14

A café owner holding up a phone with a screenshot of the menu board behind the counter

Watch the check in 74 seconds1:14

The agent publishes, waits for the Player to confirm playback, then screenshots the glass, catches a cut-off row and fixes it.