CLI command reference

Read the project record and its remaining credit.

project show

No parameters.

screenrig project show

data.credit_remaining is a whole integer credit count. Below 1000 the envelope may carry a credits_low warning. Until 1 Jan 2027 usage is free within reason, so remaining credit is an integer meter an agent can read, not a shutoff instruction. Standard's free monthly allowances continue after that; extra usage is optional prepaid.

Set the name people see in the dashboard project switcher.

project rename NAME

Read the project's plan, independent screens and advertiser feature flags, and effective capability set. A route denial wins over a stale capability read.

project capabilities

Create, list, or revoke project-member and ad-buyer invitations.

invitations create --email ADDRESS[,ADDRESS] [--kind member|ad-buyer] [--link]
    [--screen-id ID] [--slot-id ID] [--policy trusted|review_required]
invitations list [--kind member|ad-buyer] [--status STATUS]
invitations revoke ID

--kind defaults to member. Email delivery is the default and expires after seven days. --email accepts comma-separated recipients, up to fifty per request. --link is member-only, requires exactly one intended recipient, and returns a twenty-four-hour invitation URL once for direct handoff. Never put that URL in logs, notes, or a shared transcript. Lists never return it.

Ad buyers use email only and need an owned screen or slot scope (or both). --screen-id and --slot-id accept comma-separated IDs; --policy selects trusted or review_required. Status filters are queued, sent, issued, accepted, revoked, expired, and failed.

screenrig invitations create --email teammate@example.com
screenrig invitations create --kind ad-buyer --email buyer@example.com --screen-id scr_LOBBY --policy review_required

Agents do not accept invitations. The invited person opens the email, signs in or creates a passkey, and accepts in the dashboard. Link signup verifies their email first. Revoking an accepted invitation does not undo a membership; use the buyer membership controls to revoke advertising access.

Report whether this installation holds a usable credential.

agent status

No parameters.

screenrig agent status

Read-only. It never changes local or server state, and it costs nothing.

Sign this installation in to an existing account, with a person's approval in the dashboard.

login [--project ID] [--access read|manage] [--name NAME] [--no-wait] [--resume ID]

screenrig login --access read

Prints the dashboard address and an eight-letter code to stderr, then waits up to 10 minutes. The person checks that the code matches, chooses the project, the access level and the capabilities, and approves. The envelope reports status: signed_in, the project, the organization and access. Running it again on a signed-in installation adds a project or raises a Read only project to Manage. Denial is login_denied and expiry is login_expired.

End this installation's sign-in and remove its tokens.

logout

No parameters.

screenrig logout

Revokes the sign-in on the server, then removes the stored tokens and reports status: signed_out. A failure that might not have reached the server keeps them, so rerunning is safe. Run screenrig login to sign in again.

Open the ordinary dashboard URL. This command does not mint a sign-in link, create a session, or need an agent credential.

dashboard [open]

screenrig dashboard

The dashboard shows the person's projects after sign-in. Browser project selection does not change the project bound to an agent.

Request a sign-in reset email without an agent credential.

dashboard reset-sign-in --email ADDRESS

The acknowledgment does not reveal whether the email has a login. The emailed reset expires after one hour; the person creates a new passkey. Completion replaces their sign-in credentials and revokes other sessions.

Check this installation and report every check by name.

doctor [--repair-config]

screenrig doctor

data.checks names each check and its status: the Node runtime, the resolved configuration path and its permissions, the control-plane origin and its service routes, the advertised feedback capability, and the optional media toolchain (ffmpeg, ffprobe, encoder_libx264, encoder_libx265, encoder_libwebp, cwebp, filter_hdr_tonemap).

Any failed check makes doctor exit non-zero, so read the individual names before calling the installation unhealthy. A missing media toolchain affects media upload alone.

Print the bundled CLI version and its protocol adapter.

version

No parameters.

screenrig version

Run this first in a session. A successful envelope proves the launcher resolved the bundled CLI. --version and -V do the same thing from anywhere on the command line.

List this project's service clients, live and revoked, with their keys, secret ids and usage.

service-client list

No parameters.

screenrig service-client list

Never returns a secret.

Show one service client.

service-client show ID

screenrig service-client show scl_ID

Lists each key's kid and each secret's css_ id for rotation.

Create a service client owned by this project.

service-client create --name NAME [--capability NAME]... [--access read|manage] [--key-file PATH] [--secret-file PATH]

screenrig service-client create --name "Nightly report" --access read --capability reports --key-file screenrig-client.pem

Needs the project capability and Manage. At most 50 live clients per project. A key without its own kid is known by its RFC 7638 thumbprint.

Register a second public key for a rotation without downtime.

service-client add-key ID --key-file PATH

screenrig service-client add-key scl_ID --key-file new.pem

A client holds at most two keys.

Generate a second secret for a rotation without downtime.

service-client add-secret ID --secret-file PATH

screenrig service-client add-secret scl_ID --secret-file new-secret

A client holds at most two secrets. The current one keeps working until you remove it.

Remove a key; tokens issued with it stop working within seconds.

service-client remove-key ID --kid KID

screenrig service-client remove-key scl_ID --kid KID

A client keeps at least one key or secret.

Remove a secret; tokens issued with it stop working within seconds.

service-client remove-secret ID --secret-id css_ID

screenrig service-client remove-secret scl_ID --secret-id css_ID

Revoke a service client permanently.

service-client revoke ID --yes

screenrig service-client revoke scl_ID --yes

Deletes its keys and secrets; its tokens stop working within seconds. The record stays for audit.

Generate a presentable whole-page still into the project media store.

media generate --prompt TEXT [--aspect-ratio RATIO] [--quality low|medium|high] [--tag TAG]
               [--no-progress]

screenrig media generate --prompt "A 16:9 restaurant menu poster for North Lobby Cafe. Dark walnut, gold type. Title NORTH LOBBY CAFE. Items: Espresso $4, Cortado $4.50, House Blend $3. Footer Open 7am to 7pm. Typeset every line of copy in the image." --aspect-ratio 16:9 --quality high --tag LobbyMenu

The command stores a lossy WebP in the project media store and returns data.media_id (med_…). Do not re-upload the bytes. Never print pixels or the prompt. The authoring tree and prompt contract live on Compose.

Convert a local file to delivery bytes, upload it, and wait until the object is ready.

media upload <file> [--content-type TYPE] [--tag TAG] [--no-wait] [--poll-ms MS]
             [--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
             [--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
             [--preset signage-1080p30|signage-4k30] [--no-audio]

screenrig media upload ./lobby-welcome-loop.mp4 --tag LobbyLoop

Video becomes an MP4: H.264 High profile level 4.2 by default, or H.265 with --codec hevc, in yuv420p tagged Rec. 709. An HDR source is tone mapped to Rec. 709. Audio, where the source has any, is AAC at 192 kbit/s, 48 kHz, stereo.

Stills become lossy WebP at quality 90, keeping alpha where the source has it. An animated source loops forever. A WebP that already fits the size bound is passed through rather than re-encoded.

Audio becomes an MP3 for a playlist soundtrack. An MP3 source uploads unchanged; WAV, AAC, M4A, OGG and FLAC sources are converted to a 192 kb/s MP3, which needs an ffmpeg build with libmp3lame. A track runs from 1 second to 4 hours. playlist init turns audio inputs into soundtrack tracks rather than pages. The ready object is an audio media object with a duration. It cannot be placed on a page; name it in the playlist audio soundtrack instead.

The ready object id is data.media_id. The same value is data.id and data.operation.result.media_id. That id is what a playlist selector takes.

A low-information filename such as video.mp4 adds an advisory generic_filename warning to the envelope. The upload still succeeds and the CLI never renames the file; pick the name before you run the command.

Conversion runs ffmpeg and ffprobe from PATH, or from the absolute paths in SCREENRIG_FFMPEG and SCREENRIG_FFPROBE. Stills prefer the ffmpeg libwebp encoder and fall back to cwebp on PATH or SCREENRIG_CWEBP. Run doctor before the first upload of a session.

--preset signage-1080p30 bounds the long edge to 1920, the short edge to 1080, and the rate to 30 fps. signage-4k30 bounds the long edge to 3840, the short edge to 2160, and the rate to 30 fps. Both work with landscape, portrait, and square content. --no-audio omits audio encoding for silent clips. These options apply only to video.

screenrig media upload ./lobby.mov --preset signage-1080p30 --no-audio

Upload many local files from a manifest, resuming from a required state file.

media upload-batch <manifest.json> [--state FILE] [--concurrency N]
                   [--no-transcode] [--tag TAG] [--no-progress]

screenrig media upload-batch ./images.json --state ./upload-state.json

The envelope carries data.items[] in manifest order, each with path, source_filename, sha256, outcome (accepted or resumed), and media_id. data.failed[] carries items that did not land.

Read one media object, including its current revision.

media show <id>

screenrig media show med_01EXAMPLEIMAGE0000000000

Write a stored rendition to disk for inspection. Never print the bytes.

media download <id> [--output FILE]

screenrig media download med_01EXAMPLEIMAGE0000000000 --output ./lobby.webp

The envelope reports media_id, path, bytes, sha256, content_type, primitive, filename, optional source_filename, and width / height. It never carries pixels. Use this to proof a generated still before it goes on glass.

List media objects, optionally filtered by tag and primitive.

media list [--tag TAG] [--primitive image|video|audio]

screenrig media list --tag LobbyLoop --primitive video

Change or clear the tag on one object. Nothing else about a media object is patchable.

media update <id> (--tag TAG | --tags TAG1,TAG2 | --clear-tag) [--expect-rev REVISION]

screenrig media update med_01EXAMPLEIMAGE0000000000 --tag LobbyLoop

Delete one media object.

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

screenrig media delete med_01EXAMPLEIMAGE0000000000

Pack a static directory into a deterministic archive without uploading it.

app pack <directory> [--output FILE]

screenrig app pack ./lobby-board --output ./lobby-board.tgz

The envelope reports sha256, compressed_bytes, expanded_bytes, file_count, the entry list, and whether the SDK runtime was injected. app upload packs the directory itself, so reach for this command only when you want to inspect the archive first.

Applications run under a content security policy that blocks inline code. Packing moves inline style and script blocks into files under _screenrig/inline/ and links them in. Inline event handlers such as onclick= and javascript: URLs cannot be moved; packing refuses them and names the file and line.

Pack a directory, publish it as a new application release, and wait for the publication to succeed.

app upload <directory> [--name NAME] [--no-wait] [--poll-ms MS] [--timeout MS]

screenrig app upload ./lobby-board --name "Lobby board"

Read three fields: data.operation.state is succeeded, data.application.release_id is the rel_ id an application primitive pins, and data.application.id is the app_ id the kv commands take. A succeeded operation, not a release id on its own, is what means the release is usable.

Every app upload creates a new application and a first immutable release. To publish a later release of the same app, use app update. A playlist keeps serving the release it already pins until you edit that primitive.

Publish a new release of an existing application, preserving identity, name, and application K/V.

app update <id> <directory> [--expect-rev REVISION] [--no-wait] [--poll-ms MS]

screenrig app update app_01EXAMPLEAPP00000000000 ./lobby-board

Wait for data.operation.state: "succeeded", then use playlist replace-release to review the exact page, primitive, new release, and affected screens. Apply with the returned impact token and an optional revision guard as described in the playlist workflow. Existing playlist pins remain unchanged until apply. On a revision conflict, read the app again before deciding whether to retry; do not create a replacement application just to bypass the conflict.

List the project's applications.

app list

No parameters.

screenrig app list

Read one application.

app show <id>

screenrig app show app_01EXAMPLEAPP00000000000

latest_ready_release is absent until a first publish reaches ready. Publish state lives on the operation and the release, not on the application.

Print the fail-closed catalog of page keys, named regions, region fields, card plates, enter and motion enums, viewing distances, installed fonts, and examples.

compose catalog

No parameters.

screenrig compose catalog

Render a spec to a directory of region PNGs and manifest.json.

compose render <file> [--output DIRECTORY] [--combined] [--target-width PX --target-height PX] [--safe-area] [--open] [--lint-only]

screenrig compose render ./lobby-welcome.json --output ./lobby-welcome

Never print image bytes. Read manifest.json and the region PNGs before any upload.

Render a deck and write a contact-sheet preview.

compose batch <file> --output DIRECTORY [--only ID] [--target-width PX --target-height PX] [--safe-area] [--lint-only]

screenrig compose batch ./deck.json --output ./rendered --target-width 3840 --target-height 2160 --safe-area

One command accepts 1 to 2000 pages. compose render of a deck file is enough when you do not need the contact sheet.

List the keys stored for one application.

kv list --app-id ID

screenrig kv list --app-id app_01EXAMPLEAPP00000000000

Read one key.

kv get --app-id ID <key>

screenrig kv get --app-id app_01EXAMPLEAPP00000000000 menu

Write one key from JSON, a file, or base64 bytes.

kv set --app-id ID <key> --json-value JSON [--expect-rev REVISION]
kv set --app-id ID <key> --file FILE [--content-type TYPE] [--expect-rev REVISION]
kv set --app-id ID <key> --value-base64 BASE64 [--content-type TYPE] [--expect-rev REVISION]

screenrig kv set --app-id app_01EXAMPLEAPP00000000000 menu --json-value '{"soup":"lentil"}'

Delete one key.

kv delete --app-id ID <key> [--expect-rev REVISION]

screenrig kv delete --app-id app_01EXAMPLEAPP00000000000 menu

Prepare an editable full-screen playlist from local media files, ready media IDs, application release IDs, or HTTPS URLs.

playlist init <inputs...> --name NAME --output FILE [--overwrite] [--screen-id ID]
              [--target-width PX --target-height PX] [--duration-ms MS] [--fit contain|cover|fill]
              [--no-transcode] [--no-progress] [--poll-ms MS]

screenrig playlist init med_POSTER med_VIDEO --name "Lobby loop" --screen-id scr_LOBBY --output lobby.json

Preparation writes the local document and may upload media; it neither creates a remote playlist nor assigns a screen. Inspect the document and preview, then screen publish. See Prepare, publish, and edit playlists.

Print the local catalog of slide template ids.

playlist templates

No parameters.

screenrig playlist templates

Templates run locally and expand to wire primitives. A template that would emit vector chrome fails with usage_error pointing at the Compose reference, because copy and chrome are composed locally and placed as one image.

Validate a playlist document locally before create or update. No network.

playlist validate <file> [--lint-only]

screenrig playlist validate ./lobby-loop.json

Errors name exact JSON paths. A pass means local shape and cross-field semantics are valid; authorization, media readiness, dynamic selector counts, durations, and remote availability still require server checks. Create and update run this check before their write.

Composite every page to PNG frames for inspection. Never print pixels.

playlist preview <file|id> --output DIR [--frame-ms MS] [--contact-sheet] [--lint-only]

screenrig playlist preview ./lobby-loop.json --output ./frames --contact-sheet

Writes three PNGs per page: <page-id>.rest.png, <page-id>.entry.png, and <page-id>.motion-mid.png. Iframe and application regions are labelled placeholders. Look at the contact sheet before publishing.

Create a playlist from a JSON document.

playlist create <file>

screenrig playlist create ./lobby-loop.json

The envelope's data.id is the pl_ id that screen assign takes.

Replace a playlist document.

playlist update <id> <file> [--expect-rev REVISION]

screenrig playlist update pl_01EXAMPLEPLAYLIST000000 ./lobby-loop.json

Read one playlist, including its current revision.

playlist show <id>

screenrig playlist show pl_01EXAMPLEPLAYLIST000000

List the project's playlists.

playlist list

No parameters.

screenrig playlist list

Delete one playlist.

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

screenrig playlist delete pl_01EXAMPLEPLAYLIST000000

Write one playlist and every rendition it resolves into a portable bundle directory.

playlist export <id> --output DIRECTORY [--skip-applications]

screenrig playlist export pl_01EXAMPLEPLAYLIST000000 --output ./lobby-bundle

The bundle holds a manifest, the playlist document, and content-addressed media files. Dynamic all and tag selectors are snapshotted to exact ids, iframe URLs are preserved, and comments are excluded. Application primitives cannot be exported: by default they stop the export before anything is downloaded, and --skip-applications exports the rest.

Create a playlist from a bundle directory, or update an existing one from it.

playlist import <directory> [--name NAME] [--update ID [--expect-rev REVISION]]

screenrig playlist import ./lobby-bundle
screenrig playlist import ./lobby-bundle --name "Lobby loop (copy)"

Playlist display names may repeat. Import creates a separate playlist even when its name matches; use --update with an ID to replace an existing playlist.

Import validates the whole bundle locally before it touches the project: manifest, document, paths, media kinds, lengths, and hashes. Existing media are reused on an exact filename, media type, byte length, hash, and tag match; the rest are uploaded without conversion, and the playlist is written only after every object is ready.

Import never deletes or prunes remote media. If a later step fails after an upload has started, the error lists the objects confirmed ready and says whether the playlist write began. Retrying the same bundle reuses those objects.

List screens. Archived screens are omitted unless you ask for them.

screen list [--state archived] [--tag TAG]

screenrig screen list --tag Lobby

Each row carries the screen's tags. With --human, the table adds a TAGS column when any listed screen has tags.

Read one screen, including revision, assignment, and liveness.

screen show <id>

screenrig screen show scr_01EXAMPLESCREEN00000000

tags lists the screen's fleet tags. effective_playlist, takeover, and playlist_schedule report what the screen plays and why; see Schedules and takeover. health and the Player's host capabilities are in Device health and power. online is true while a Player is connected, including a short reconnect window. Optional last_online_at and last_ip appear after the first connect. Optional observation reports the surfaces a Player has painted: id, width, height, pixel_ratio, and presentation. All of these are read-only; screen update cannot send them, and an archived screen still returns its row.

Patch a screen's name, playlist assignment, or timezone in one call.

screen update <id> [--name NAME] [--playlist-id ID] [--timezone ZONE] [--expect-rev REVISION]

screenrig screen update scr_01EXAMPLESCREEN00000000 --name "Lobby"

Create a new playlist from a prepared file and assign it to a screen.

screen publish <id> <file> [--expect-rev REVISION]

screenrig screen publish scr_LOBBY lobby.json

This creates a new playlist and assigns it. It does not update an existing playlist by name. Inspect the prepared document and preview first. Repeat identical input to resume an ambiguous failure. Assignment readback does not prove playback; request a screenshot separately. See Prepare, publish, and edit playlists.

Point a screen, or a fleet of screens, at a playlist.

screen assign (<id>... | --tag TAG) --playlist-id ID [--expect-rev REVISION]

screenrig screen assign scr_01EXAMPLESCREEN00000000 --playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen assign --tag Lobby --playlist-id pl_01EXAMPLEPLAYLIST000000

If the playlist schedules any page and the screen has no timezone, the CLI refuses before sending anything and names the screen set-timezone command to run. No revision is consumed by that refusal. In a fleet, each screen applies that rule on its own: a screen with no timezone fails in its result and the others are assigned.

To publish to a fleet, create the playlist once with playlist create, then run screen assign --tag TAG --playlist-id ID. screen publish targets one screen.

Set the civil timezone a scheduled playlist is read in.

screen set-timezone <id> --timezone ZONE [--expect-rev REVISION]

screenrig screen set-timezone scr_01EXAMPLESCREEN00000000 --timezone America/Los_Angeles

Page schedules are civil times, so they are meaningless without a zone. Changing the zone remints the manifest revision.

Hide a screen and darken its glass.

screen archive <id> [--expect-rev REVISION]

screenrig screen archive scr_01EXAMPLESCREEN00000000

Archiving hides the screen from the default listing and darkens the glass. It does not unbind the Player.

Restore an archived screen to the default listing.

screen unarchive <id> [--expect-rev REVISION]

screenrig screen unarchive scr_01EXAMPLESCREEN00000000

A Player can also archive its own screen: a confirmed reset on a native Player, or unpairing a browser Player. screen show then reports archive_reason as device_reset or device_unpair (project for an archive you request), with archived_at. The screen keeps its device binding for every reason, so a Player that still holds that key or device cookie stays dark and resumes on unarchive with no re-pairing. The Player that was reset or unpaired drops its key or cookie and pairs again as a new screen. A key replaced by a confirmed screen recovery stays retired.

Delete a screen.

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

screenrig screen delete scr_01EXAMPLESCREEN00000000

Delete is not a way to detach a Player: a live screen returns screen_archive_required. Archive it instead.

Issue a new public id for a screen.

screen rotate-public-id <id> [--expect-rev REVISION]

screenrig screen rotate-public-id scr_01EXAMPLESCREEN00000000

Ask a screen's Player, or every Player in a fleet, to reload once.

screen reload (<id>... | --tag TAG) [--expect-rev REVISION]

screenrig screen reload scr_01EXAMPLESCREEN00000000
screenrig screen reload --tag Lobby

The answer carries a reload_id and an expires_at ten minutes later. A web Player reloads at its next page boundary; a native Player reconnects, refetches its manifest, and checks for an update. A Player ignores a reload within ten minutes of the last one it acted on. Reload works on active and archived screens and does not change the screen revision.

Post one transient message as stage chrome on a live screen or a fleet.

screen toast (<id>... | --tag TAG) --text TEXT [--level info] [--duration-ms MS]

screenrig screen toast scr_01EXAMPLESCREEN00000000 --text "Lobby closed"
screenrig screen toast --tag Lobby --text "Closing in ten minutes"

A toast is not a primitive: it occupies no canvas slot, has no layer, and takes no part in readiness or crossfade. Latest wins, there is no queue and no cancel, and the accepted envelope is { expires_at } only. Never put credentials or other secret material in the text.

Capture one still of an active screen, or of every screen in a fleet, and write it to disk.

screen screenshot <id> [--output FILE] [--timeout MS] [--poll-ms MS]
screen screenshot (<id> <id>... | --tag TAG) [--output DIRECTORY] [--concurrency N] [--timeout MS] [--poll-ms MS]

screenrig screen screenshot scr_01EXAMPLESCREEN00000000 --output ./lobby.webp

screenrig screen screenshot --tag Lobby --output ./lobby-shots

The command blocks until the WebP is on disk; there is no --no-wait. The envelope reports screen_id, capture_id, path, bytes, sha256, width, and height, and never image bytes. Latest wins: a later request replaces an in-flight capture.

For several ids or --tag, the answer is a fleet result with action: "screenshot", the selector, and the output directory; each ok result carries path, bytes, sha256, width, and height. With --tag, the CLI first lists the tagged screens, following every list page; each list page is billed and the captures themselves are free, and several ids need no list. --idempotency-key is refused in this form, because each capture uses its own key. If a capture fails unexpectedly, that screen's result is unexpected_error, no new captures start, the screens still waiting report not_attempted, and the exit code is 1.

Set, add, remove, or clear the tags on a screen or a fleet.

screen tag (<id>... | --tag TAG) (--set TAGS | --add TAGS | --remove TAGS | --clear) [--expect-rev REVISION]

screenrig screen tag scr_01EXAMPLESCREEN00000000 --set Lobby,Floor2
screenrig screen tag scr_01EXAMPLESCREEN00000000 --add Spring
screenrig screen tag --tag Lobby --add Spring

A tag is 1 to 32 letters or digits, and a screen carries at most 16 unique tags. Tags select fleets; they are never authorization and never reach the Player. Changing tags bumps the screen revision, not the manifest revision. For one screen the envelope is the updated screen. --add and --remove read the screen first and write the new set guarded by --expect-rev or the revision just read, so a concurrent change returns revision_conflict (exit 6) instead of being overwritten; rerun the command. In a fleet, --add and --remove apply against each screen's stored set atomically, and a screen that would pass 16 tags fails in its own result with invalid_request.

Show a screen's playlist schedule and the playlist it currently selects.

screen schedule show <id>

screenrig screen schedule show scr_CAFE

The JSON output can go straight back to screen schedule set --file.

Replace the playlist schedule on a screen or a fleet.

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

screenrig screen schedule set scr_CAFE --file dayparts.json
screenrig screen schedule set --tag Cafe --file dayparts.json

Every playlist a schedule names is validated as an assignment, and the screen needs a timezone and an assigned default playlist. Outside every window the assigned playlist plays. If a scheduled playlist later cannot be shown, its entries are skipped and screen.playlist_unavailable is recorded.

Remove the playlist schedule from a screen or a fleet.

screen schedule clear (<id>... | --tag TAG) [--expect-rev REVISION]

screenrig screen schedule clear --tag Cafe

Show one playlist on a screen or a fleet ahead of the schedule and the assignment.

screen takeover [set] (<id>... | --tag TAG) --playlist-id ID [--until TIME | --for DURATION] [--reason TEXT] [--expect-rev REVISION]

screenrig screen takeover scr_LOBBY --playlist-id pl_DRILL --for 30m --reason "Fire drill"
screenrig screen takeover --tag Lobby --playlist-id pl_LAUNCH --for 2h
screenrig screen takeover scr_A scr_B --playlist-id pl_NOTICE --until none

screen takeover ID is short for screen takeover set ID. A new takeover replaces the previous one. When it ends, the screen returns to its schedule or assigned playlist on its own. A takeover whose playlist cannot be shown ends. A --for rerun after an ambiguous failure computes a new end and is sent as a new request.

End the takeover on a screen or a fleet.

screen takeover clear (<id>... | --tag TAG) [--expect-rev REVISION]

screenrig screen takeover clear --tag Lobby

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

screen reboot (<id>... | --tag TAG) [--yes] [--expect-rev REVISION]

screenrig screen reboot scr_LOBBY
screenrig screen reboot --tag Lobby --yes

The Player reboots the device, not just itself. A reboot request expires after ten minutes. A refused or failed request, and an exact replay of the same request, do not count toward the per-screen limit.

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

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

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

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. The Player applies every change at once and reports the power it achieved.

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

screen display-schedule show <id>
screen display-schedule set (<id>... | --tag TAG) --file FILE [--expect-rev REVISION]
screen display-schedule clear (<id>... | --tag TAG) [--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 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. The saved output of display-schedule show can be edited and sent back with set --file.

{"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.

Read the comment object on a screen, a playlist, or one playlist page.

comment show screen <id>
comment show playlist <id> [--page PAGE_ID]

screenrig comment show screen scr_01EXAMPLESCREEN00000000

An unset comment reads as { "comments": null }. screen show and playlist show include comments when the server sends it.

Write the comment object.

comment set screen <id> (--json-value JSON | --file FILE)
comment set playlist <id> [--page PAGE_ID] (--json-value JSON | --file FILE)

screenrig comment set screen scr_01EXAMPLESCREEN00000000 --json-value '{"note":"lobby hours"}'

Playlist create and update cannot set comments; that is what these commands are for.

Remove the comment object.

comment delete screen <id>
comment delete playlist <id> [--page PAGE_ID]

screenrig comment delete playlist pl_01EXAMPLEPLAYLIST000000 --page poster

Read one operation's current state.

operations show <id>

screenrig operations show op_01EXAMPLEOPERATION00000

Poll one operation until it finishes.

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

screenrig operations wait op_01EXAMPLEOPERATION00000

Ask the control plane to cancel one operation.

operations cancel <id>

screenrig operations cancel op_01EXAMPLEOPERATION00000

Read one finite page of project events.

events list [--after CURSOR] [--limit N]

screenrig events list --limit 25

The default output is one JSON envelope for the page. With --human, output is one logfmt line per event: at=, type=, severity=, and scalar details.

Stay on the event stream and print events as they arrive.

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

screenrig events follow

A disconnect or transient failure reconnects with backoff and resumes from the last event id. Replay after a reconnect is free. Authorization and not-found problems stop the command rather than retrying it.

The default output is NDJSON: one envelope per event on its own line, rather than a single envelope. Use --human for logfmt lines.

Register an HTTPS endpoint and receive its signing secret once.

webhooks create --url URL --event-types TYPES [--description TEXT] [--disabled]

screenrig webhooks create --url https://hooks.example.com/screenrig --event-types "screen.*,playlist.updated"

The envelope is the webhook with its signing secret in data.secret (whsec_…) and the warning webhook_secret_shown_once. Store the secret in the receiver's secret store right away. No other command returns it, and the CLI never writes it to its configuration, operation log, or write-recovery state. After an interrupted or ambiguous create, rerun the identical command within 24 hours: it reuses the saved idempotency key, and the server returns the same answer, secret included.

List this project's webhooks, never their secrets.

webhooks list

screenrig webhooks list

Inspect a webhook and its delivery health.

webhooks show <id>

screenrig webhooks show whk_01EXAMPLEWEBHOOK00000

status is active, failing while no delivery has succeeded since failing_since, or disabled. After 72 hours of continuous failure the webhook is disabled with disabled_reason: delivery_failures, and the event log records webhook.disabled. last_success_at and last_failure_at report the latest outcomes.

Change a webhook's URL, event types, description, or enabled state.

webhooks update <id> [--url URL] [--event-types TYPES] [--description TEXT | --clear-description]
                     [--enable | --disable] [--expect-rev REVISION]

screenrig webhooks update whk_01EXAMPLEWEBHOOK00000 --enable

update changes only the fields you pass. Events from while the webhook was disabled are not delivered after --enable.

Delete a webhook. Its pending deliveries fail with webhook_deleted.

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

screenrig webhooks delete whk_01EXAMPLEWEBHOOK00000

Replace a webhook's signing secret and receive the new one once.

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

screenrig webhooks rotate-secret whk_01EXAMPLEWEBHOOK00000

The envelope carries the new secret in data.secret with the warning webhook_secret_shown_once; store it right away. The previous secret stops signing, but at most one attempt already in flight can still arrive signed with it, so accept both for a short while. After an interrupted or ambiguous rotation, rerun the identical command within 24 hours to get the same secret back.

Queue one webhook.test delivery to this webhook only.

webhooks test <id>

screenrig webhooks test whk_01EXAMPLEWEBHOOK00000

The envelope is the queued delivery. It is attempted once without retries, works on a disabled webhook, is metered like any delivery, and never changes the webhook's failure state. At most 20 test deliveries a minute per project; more is rate_limited (exit 7). Read the outcome with webhooks deliveries.

Read a webhook's delivery log, newest event first.

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

screenrig webhooks deliveries whk_01EXAMPLEWEBHOOK00000 --limit 20

Each row is one event: event_id, event_type, state (pending, succeeded, or failed), attempts, last_status, and a fixed last_error class such as http_status, timeout, connection_failed, tls_failed, dns_failed, or url_rejected. Rows never include the receiver's response. next_cursor is null at the end of the log. A failed attempt is retried with backoff, 30 seconds doubling to one hour, for 24 hours, then the row is failed.

Read per-play records, one row per visible start.

playback plays [--from TIME] [--to TIME] [--screen-id ID] [--media-id ID] [--tag TAG] [--cursor CURSOR] [--limit N] [--all]
playback plays --format csv [--output FILE] [--from TIME] [--to TIME] [--screen-id ID] [--media-id ID] [--tag TAG]

screenrig playback plays --from 7d --tag Lobby --all
screenrig playback plays --format csv --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z --output september-plays.csv

The CLI normalizes both bounds to UTC and sends them on every request; data.from and data.to echo them. The newest 5 seconds are held back until they settle, so a play appears about 5 seconds after it is received, and data.to reports that effective end. JSON returns one page in data.items with data.next_cursor, and data.next.argv is the exact command for the next page. --all stops early, with data.next and a warning, at the page cap (playback_plays_truncated) or when the export budget is spent (playback_export_rate_limited), rather than spending requests into a refusal.

The CSV is RFC 4180 with the fixed header row screen_id,playlist_id,page_id,primitive_id,media_id,primitive,started_at,received_at,manifest_revision,playlist_revision, times in RFC 3339 UTC. primitive_id and started_at are empty unless the Player reported them. A cell that begins with =, +, -, @, tab, or carriage return carries a leading ' so spreadsheets do not evaluate it. The CLI writes through a private temporary file in the same directory and replaces an existing file only after the stream ends cleanly. --timeout is the no-progress limit for the stream, 60000 ms without a byte by default, not a limit on its total duration. The envelope reports path, bytes, rows, sha256, and last_received_at; the CSV never enters the envelope.

If a stream fails partway, the command exits non-zero and never writes the target file. The complete rows already received stay in FILE.partial, and error.next exports the rest of the range from the last received_at into an unused FILE-rest.csv. Rows received at that exact instant appear in both, so drop the repeats when joining them.

Read daily playback totals for this project, newest days first.

playback list [--screen-id ID] [--media-id ID] [--day YYYY-MM-DD | --day-from YYYY-MM-DD --day-to YYYY-MM-DD] [--format csv] [--output FILE]

screenrig playback list --screen-id scr_01EXAMPLESCREEN00000000 --day 2026-08-14
screenrig playback list --format csv --day-from 2026-09-01 --day-to 2026-09-30

One row per screen, media object, and UTC day. The filters select the caller's own rows. The CSV header row is screen_id,media_id,filename,primitive,day,play_count,last_page_id,last_manifest_revision,first_started_at,last_started_at. A failed daily export keeps nothing; rerun it.

File a bug report against screenRIG.

feedback bug <title> (--body TEXT | --body-file FILE) [--command "GROUP ACTION"] [--no-context]

screenrig feedback bug "Playlist stalls after assignment" --body-file ./report.md --command "screen assign"

The server rejects, rather than redacts, text matching credential material, and returns field-level guidance so you can rewrite and resend. An exact retry under the same idempotency key returns the original submission for twenty-four hours.

File a feature request.

feedback feature <title> (--body TEXT | --body-file FILE) [--command "GROUP ACTION"] [--no-context]

screenrig feedback feature "Add a dry-run flag" --body "Preview a change first."

List this project's own submissions.

feedback list [--kind bug|feature]

screenrig feedback list --kind bug

Buyer: list the networks this project was invited into, and inspect one network's permitted inventory and slots.

ads networks list
ads networks show <seller-project-id>

screenrig ads networks list

Seller: inspect or create this project's own network and set its default rate.

ads network show
ads network create --name NAME
ads network rate --rate-mcr-per-15s MCR --expect-rev REVISION

screenrig ads network rate --rate-mcr-per-15s 1000 --expect-rev 3

The rate is per 15 seconds of completed playback. A changed effective rate pauses affected campaigns until each buyer accepts a fresh quote.

Seller: opt an owned screen in or out of advertising and describe it to invited buyers.

ads inventory list
ads inventory update <screen-id> [--enabled | --disabled] [--site-name NAME]
    [--city CITY] [--region REGION] [--venue-type TYPE] [--audience-tags TOKENS]
    [--placement TEXT] [--public-description TEXT]
    [--rate-mcr-per-15s MCR | --clear-rate] [--expect-rev REVISION]

screenrig ads inventory update scr_LOBBY --enabled --venue-type cafe

Omitted flags keep their current values. A new inventory row needs --enabled or --disabled.

Seller: define reusable ad slots. A slot changes nothing on the glass until its adslot page is placed in a playlist.

ads slots list
ads slots create --name NAME --accepted-media image,video
    [--max-image-duration-ms MS] [--max-video-duration-ms MS]
    [--rate-mcr-per-15s MCR] [--enabled | --disabled]
ads slots update <slot-id> --expect-rev REVISION [same fields]

screenrig ads slots create --name "Lobby break" --accepted-media image,video

Use the shared invitations commands above:

screenrig invitations create --kind ad-buyer --email owner@bakery.example --screen-id scr_LOBBY --policy review_required
screenrig invitations list --kind ad-buyer
screenrig invitations revoke ID

The invited person accepts in the dashboard. A signed-in person selects their buying project and confirms with a fresh passkey proof. A person without a login creates one and an advertiser-only project during acceptance.

Seller: change or revoke an admitted buyer's review policy and inventory scope.

ads memberships list
ads memberships update <membership-id> --expect-rev REVISION
    [--policy trusted|review_required] [--screen-id IDS] [--slot-id IDS]
ads memberships revoke <membership-id>

screenrig ads memberships list

Revocation stops new ad plays and keeps financial history.

Buyer: bind ready owned media to an immutable creative with approved copy.

ads creatives list
ads creatives create --media-id ID --copy TEXT
ads creatives show <creative-id>

screenrig ads creatives create --media-id med_123 --copy "Fresh bread daily"

Buyer: draft a campaign, price it, and activate it by accepting the quote.

ads campaigns list | show <campaign-id>
ads campaigns create <file>
ads campaigns update <campaign-id> <file> --expect-rev REVISION
ads campaigns preview <campaign-id> [--expect-rev REVISION]
ads campaigns activate <campaign-id> --quote-id ID --expect-rev REVISION
ads campaigns pause | resume <campaign-id> --expect-rev REVISION
ads campaigns accept-rates <campaign-id> --quote-id ID --expect-rev REVISION

screenrig ads campaigns preview cmp_123

A draft reserves nothing. preview returns a time-limited quote and spends nothing; activate requires that exact quote. After a seller rate change, only accept-rates with a fresh quote resumes the campaign.

Seller: approve or reject exact submitted creative versions from buyers on review_required.

ads reviews list
ads reviews show <review-id>
ads reviews approve <review-id>
ads reviews reject <review-id> --reason TEXT

screenrig ads reviews list

Read spend as a buyer or delivery as a seller.

ads reports spend --campaign-id ID
ads reports delivery --from TIMESTAMP --to TIMESTAMP

screenrig ads reports delivery --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z

Delivery reports gross, serving fee and net for the period. A buyer report never shows a seller's other income.