Bundled CLI surface
Commands are grouped the way the CLI groups them. Installation and first use are covered in Quickstart; the choice between upload, cards and selectors is covered in Compose.
| Group | Commands | What it covers |
|---|---|---|
| Projects | project organization invitations agent login billing doctor | Create, select, rename, move and export projects, sign in and out, invite people, read plan limits and advertising amounts, and run doctor. |
| Service clients | service-client | Create service clients, add and remove their keys and secrets, and revoke them: the sign-in for servers, scripts and CI jobs. |
| Help and support | help status docs recovery support feedback | Search the documentation, check service status, recover from a write with an unknown outcome, talk to support and send bug reports or requests. |
| Media | media media folder | Upload, replace, version, tag, move and delete images, video and audio, with folders, dynamic selectors and availability rules. |
| Media sync | media sync media sync account | Keep a media folder in step with SharePoint, OneDrive, Dropbox or Google Drive: add accounts, create syncs, run them and read their results. |
| Playlists | playlist | Prepare, validate, create, patch, export and import playlists, manage their pages, revisions and instances, and replace an application release. |
| Cards | card cards kv webhook | Find card types, create a card, set its parameters and live data, preview it and update its data from outside systems through signed webhooks. |
| Applications | app kv kv webhook | Pack, upload, update and delete web applications, and read or write their key/value store and its webhooks. |
| Screens | screen browser setup | Pair, list, publish to, assign, tag, move, reload, capture and delete screens, and manage folders, links, video walls and live view. |
| Schedules | screen schedule screen takeover schedule import | Set, preview, restore and clear a screen's playlist schedule, take screens over for a while and import schedules from a sheet. |
| Campaigns | campaign | Create, preview, publish, promote, pause and restore campaigns that switch a whole audience of screens to a playlist while their rules hold. |
| Device health | screen reboot screen display screen brightness screen uptime | Reboot, restart and update a device, schedule its display and reboots, set brightness, lock the kiosk and read uptime, health and storage. |
| Reviews and notes | reviews comment notes | List, show and withdraw reviews of agent changes, attach comments to screens and playlists and leave project notes for later sessions. |
| Notifications | notifications webhooks alerts events operations | Tell people and systems when a screen changes state with notifications and webhooks, follow the event log, work alerts and wait on operations. |
| Reports | reports audit playback | Build reports and schedule them by email, read and verify the audit log, and query playback evidence: plays, totals and completeness. |
| Data sources | feeds source connection | Read third-party feeds, keep a card current from an outside address on a schedule and save Microsoft and Google connections. |
| BI dashboards | bi connection bi view | Connect Grafana, Tableau, Power BI or a web dashboard, then browse, create, test and show its views on screens. |
| Triggers | triggers | Take screens over from CAP emergency alerts and show overlays posted by Home Assistant, sensors or any HTTP client: create, test and rotate triggers. |
| Fleet links | fleet-links migrate | Create fleet links for device managers and move another signage platform's media, playlists, schedules and screens into screenRIG. |
| Advertising | ads | Buy ads in a network that invited you or sell ad breaks on your screens: networks, inventory, slots, creatives, campaigns, reviews and reports. |
Every command runs the same way
screenrig [--json | --human] [--api-url URL] [--config PATH] [--request-id ID]
[--project-id ID] [--idempotency-key KEY] [--timeout MS] <command> [args]Global flags
| Flag | Type | Default | Notes |
|---|---|---|---|
--json | boolean | JSON for operations | Explicit JSON output, retained for compatibility. Also selects structured help. Cannot be combined with --human. |
--human | boolean | off | Select human-readable operational output. Cannot be combined with --json. |
--project-id ID | string | last-used project | Fix this invocation to a cached project without changing the selection. Each command keeps its target and recovery state for its full run. |
--api-url URL | string | https://api.screenrig.ai | Control-plane origin. SCREENRIG_API_URL sets the same thing. |
--config PATH | path | the user configuration file | Use a specific configuration file. SCREENRIG_CONFIG sets the same thing. |
--request-id ID | string | generated per run | Your own request id: req_ plus 16 to 64 letters, digits, _ or -. It goes on the first request only and is echoed back as request_id. Keep it in reports. |
--idempotency-key KEY | string | derived per write | Reuse the same key to retry an ambiguous write. The server returns the original result for twenty-four hours; a different body under the same key is idempotency_mismatch. |
--timeout MS | integer | 30000 per request | Bounds each HTTP request. On a command that waits for an operation it is the wait deadline instead, and the default is 120000. |
--help, -h | boolean | off | Print focused help for the command or group and exit. Add --json for structured help. |
--version, -V | boolean | off | Print the bundled CLI version and exit. Same as the version command. |
Environment
| Variable | Effect |
|---|---|
SCREENRIG_API_URL | Control-plane origin, overriding the stored configuration. |
SCREENRIG_CONFIG | Path to the configuration file. |
XDG_CONFIG_HOME | Base of the configuration directory. Otherwise %APPDATA%\screenrig on Windows, or ~/.config/screenrig. |
SCREENRIG_FFMPEG | Absolute path to ffmpeg, when media upload should not take it from PATH. |
SCREENRIG_FFPROBE | Absolute path to ffprobe. |
SCREENRIG_CWEBP | Absolute path to cwebp, the fallback still encoder. |
None of these is a credential: there is no token flag and no credential environment variable. The CLI reads the session the plugin stored for this installation, in a user-private file that survives a plugin upgrade, and renews it on its own. A configuration saved with screenrig login --client-id signs in as that service client instead, reading its key or secret file each time and keeping the token in memory.
Output
Operational commands write JSON to stdout by default, including errors. A single result carries an envelope: ok, then data, request_id, operation_id, and warnings[] on success, or error on failure. Progress, safe URLs, and human notes go to stderr. events follow emits NDJSON: one JSON envelope per event, on its own line. Redirecting stdout does not change the format.
Use --human for manual inspection. Event commands then print one logfmt line per event. Help and bare command groups remain readable text by default; use screenrig --json playlist --help for structured discovery. --json and --human cannot be combined.
Older plugin bundles may require explicit --json for operational results. Check the installed CLI's help when working with an older bundle. Playlist authoring files remain JSON documents; a command result envelope is not an editable playlist document.
An error envelope carries error.status, a stable error.code, and often error.next.command naming exactly what to run next. Branch on those rather than on prose.
A change that waits for a person's review is a success, not an error: ok: true, exit 0, data.status: pending_review with the review, a pending_review warning naming the review URL, and data.next pointing at reviews show ID. A retag of approved media under review is ok, exit 0, with warning media_review_pending instead: its review appears in reviews list within a few seconds. See Reviews.
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | Unexpected failure. |
2 | Usage error. Nothing was sent. |
3 | Credential problem. This installation cannot authenticate. |
4 | Not found. |
5 | Conflict. |
6 | Precondition failed, including revision_conflict: the --expect-rev revision was stale. |
7 | Rate limited. Honor Retry-After, surfaced as retry_after_seconds. |
8 | Other client-side rejection. |
9 | Server error. |
10 | Network failure. |
11 | Timed out. |
12 | Configuration error. |
13 | The operation itself failed. |
Common problem codes in the envelope:
| Code | Meaning | Next step |
|---|---|---|
not_enrolled | This installation holds no project credential yet. | Create a project with screenrig agent enroll --email ADDRESS --organization "NAME". Use screenrig login only when the user asks to use an account that already exists. |
session_ended | The sign-in was revoked, expired or ended. | screenrig login, approved by a person in the dashboard. |
insufficient_access | The session's access level cannot do this: Read only changes nothing, and Propose cannot delete, control screens or spend. | screenrig agent status shows effective_access. When access_limited_by names project or person, the project owner changes the review setting; otherwise screenrig login --access manage, approved by a person. |
approver_required | Only the project owner or a member who can approve may do this, such as giving an agent Manage. | Ask the project owner to turn on Can approve, or choose Read only or Propose. |
playlist_not_approved | The playlist has no approved version yet, so no screen can show it. | Wait for its review (screenrig reviews show ID), or choose an approved playlist. |
review_not_pending | The review was already decided, withdrawn or replaced. | screenrig reviews show ID for its state. |
login_denied, login_expired | The person denied the sign-in, or its 24-hour code expired. | Run screenrig login again. |
client_auth_failed | A service client's key, secret or id was refused. | Check the key or secret file the config signs in with (login --client-id ID --client-key-file FILE or --client-secret-file FILE) against screenrig service-client show ID. |
capability_required | The project lacks the capability this command needs, such as screens or advertiser. | screenrig project capabilities, then choose the matching --intent for a new project or change the project’s purpose. |
rate_limited | Too many requests in the current window. | Wait for retry_after_seconds, then retry. |
free_organization_limit | The person already holds their free Standard organization, so project create cannot start another. | Add the project to the organization the detail names: screenrig project create NAME --organization-id ID. Another organization needs Plus, Premium or Enterprise through the contact form at https://screenrig.ai/contact#message. |
organization_plan_required | The organization admits no new screens until a plan pays for it. | The owner moves the project with screenrig project moves and screenrig project move --organization-id ID, or the organization gets Plus, Premium or Enterprise through the contact form at https://screenrig.ai/contact#message. |
Revisions and retries
Revision guards are optional. Omit --expect-rev to write the current resource without a prior revision read. Supply it with a known revision to reject stale writes. On revision_conflict, refetch the resource, reapply the change, and retry with the returned revision. On an ambiguous transport failure, retry with the same --idempotency-key; the control plane returns the original result rather than writing twice.
Agent request cap
An organization's agents, CLI sessions and service clients make up to 500 requests an hour on Standard and Plus, 2,000 on Premium and Education and 10,000 on Enterprise, across all its projects. Nothing is charged. Past the cap a command fails with rate_limited and retry_after_seconds: wait that long, then retry once. Screens keep playing and the dashboard keeps working.
Each API call a command makes is one request. A fleet command, screen assign or screen tag with several screen ids or --tag, is one request however many screens it reaches, and screen screenshot --tag makes one request for each list page it follows. Each JSON page of playback plays or playback list is one request, and a playback CSV, XLSX or PDF export is one request for its whole range.
These do not count: project show, agent status, billing, notes list, notes show, operations wait, events follow and its replay, the screen messages screen reload, screen toast, screen identify, screen play-page, screen screenshot and screen live, notification emails, screen notices and webhook deliveries, and card data and key/value writes, which keep their own limit.
Command names and discovery
Use show to inspect a resource, list for collections, and kv get / kv set
for values. Use --name for display names, --screen-id, --app-id,
--playlist-id, and --release-id for resource selectors, --expect-rev for
revision guards, and --after for event cursors. The group is app; “application”
is the resource name. Comments keep comment ACTION screen|playlist ID.
Use screenrig help --all for the full inventory or screenrig playlist init
--help for focused help. Add --json for argument metadata, choices, defaults,
examples, and option relationships. exactlyOne, atLeastOne, atMostOne, and
together groups are checked before configuration or network access; requires
means the first option requires all remaining options. Read stdin only where
command help explicitly supports -.
Create a new project
screenrig agent enroll --email ADDRESS --organization "NAME"
agent enroll creates an identity, organization, project and membership, and stores identity and project credentials privately. Name the organization after the business the screens are for, else the person, as you know them from the conversation. Pass Screens only when you know neither, and screenRIG names the organization from the email address. The project gets a readable two-word name the person can rename. --organization is required; --name, at most 80 characters, separately names the agent.
Use the person's actual contact email. Enrollment emails a project-member
invitation; it does not disclose whether that address already has a login.
The person opens the invitation and creates a login with a passkey,
or signs in to add the project to their existing login.
Acceptance moves the project into the organization holding the person's
verified email domain, otherwise into the free Standard organization they
already hold, renamed on a name clash.
Add --intent advertising for a project that buys ads rather than pairing
screens. --setup-code CODE links the new project to the website visit that showed the code, such as K7QX-2MPD. --force replaces this installation's enrollment or pending connection
state when intentionally creating another project.
agent enroll (--email ADDRESS | --agentid-claim CODE) --organization NAME [--name NAME]
[--intent signage|advertising] [--setup-code CODE] [--force]
Sign in with AgentID
An agent with an AgentID signs in at https://api.screenrig.ai/agentid/start,
receives a claim code, installs the official plugin, and runs
screenrig agent enroll --agentid-claim CODE --organization "NAME".
The owner's verified email receives the dashboard invitation.
Sign in to an existing account
screenrig loginlogin signs this installation in to an account that already exists. It prints a dashboard address and a code, then waits up to 24 hours. A person opens the address, which carries the code, checks that it matches, adjusts the project, Read only, Propose or Manage, or the capability areas if they want, and presses Connect once; a dashboard sign-in from the last hour is the proof, so there is no second passkey prompt. The CLI stores the session, selects the approved project and returns status: signed_in with the project, organization and access.
login [--project ID] [--access read|propose|manage] [--name NAME] [--no-wait] [--resume ID]
login --client-id ID (--client-key-file PATH | --client-secret-file PATH)
logout--access asks for a level; the default is manage, and the person decides. --project suggests the project. --no-wait returns status: pending with the verification_uri_complete, the user_code and a login_ handle that holds no secret; login --resume ID waits for the approval later. Run login again on a signed-in installation to add another project or to raise a Read only or Propose project to Manage.
Each session carries capability areas: screens, content, playlists, advertising, reports, and project. A session calls only commands in its areas; reports also reads any area. A command outside them returns 403 forbidden with detail This agent credential lacks the <name> capability. Read only sessions list and read. Propose sessions also upload media, write notes and propose media, playlist and screen changes, which wait for a person's review. A change beyond the session's level returns 403 insufficient_access.
logout revokes the sign-in on the server and removes the stored tokens; in a service client's configuration it removes the saved client. A failure that might not have reached the server keeps them, so rerunning logout is safe. doctor shows when the session ends: 90 days after its last use, and at most one year after sign-in. See Authentication.
Prepare, publish, and edit playlists
For ready images and videos, prepare a full-screen playlist in playback order:
screenrig playlist init med_POSTER med_VIDEO --name "Lobby loop" --screen-id scr_LOBBY --output lobby.json
screenrig playlist validate lobby.json
screenrig screen publish scr_LOBBY lobby.json
screenrig screen screenshot scr_LOBBYValidate the document, publish it, then look at the real screen with screen screenshot. playlist init accepts local
image, video and audio files, ready med_ IDs, pinned rel_ application releases, HTTP
or HTTPS iframe URLs and pasted <iframe> embed codes in playback order, including mixed inputs:
screenrig playlist init ./poster.png med_VIDEO rel_APP https://example.com --name Lobby --screen-id scr_LOBBY --output lobby.jsonLocal files upload through the normal media path, up to four at a time, and wait for readiness. This requires ffmpeg and ffprobe unless --no-transcode is supplied. data.uploads lists each file's source, media_id, reused, and per-stage timing. Audio files and ready audio med_ IDs become the soundtrack, in input order, instead of pages. Preparation writes the local document and may upload media; it neither creates a remote playlist nor assigns a screen. Existing media must be ready. HTTP and HTTPS URLs may include LAN hosts and embedded credentials and are not fetched during preparation. A pasted <iframe> embed code is read for its src and becomes an iframe page. The Player web app requires HTTPS URLs without a username or password.
If preparation is interrupted, rerun the identical command. Nothing is written until every upload is ready, so no output file blocks the retry, and a file whose upload already finished returns its existing media ID (reused: true) instead of uploading again.
Each input except audio becomes one full-screen page with a black background and a 200 ms
crossfade. Images and videos use --fit contain|cover|fill (default contain). Videos are silent unless --sound is given, do not loop, and advance on completion. Other pages use
--duration-ms (default 8000), and an application page holds for 24 hours (86400000 ms) unless it is given. Applications and iframes use fill; application
releases are pinned with timed advancement and no controller privileges. Edit the document for application-controlled advancement. Verify release readiness and actual playback through the server and intended Player. Publishing can inspect the response headers of eligible public HTTPS iframe pages. A page whose X-Frame-Options or frame-ancestors refuses framing cannot be shown by the Player web app or the macOS, Samsung Tizen, LG webOS and BrightSign Players. When publishing detects a refusal, the write still succeeds: screen publish and playlist writes such as playlist create|update|patch print an iframe_framing_refused warning naming the page and primitive, and events list shows a playlist.iframe_framing_refused warning.
Supply --screen-id to read the target dimensions and revision. The result includes data.screen_id, data.screen_revision, and data.publish.argv. Pass this argument array to the bundled screenrig launcher without shell splitting: it preserves paths, config, and API origin. Add --expect-rev explicitly to guard against later screen changes. Target metadata stays outside the authored document. A screen with a video wall gives its wall's canvas and the matching format.
To override the canvas, supply both --target-width and --target-height. These also work without a screen, in which case no publish arguments are returned. Unknown or multiple reported surfaces require explicit dimensions. Output files are exclusive by default; use --overwrite to replace an existing authoring file atomically. An empty file does not count as existing. Parent directories are created automatically. URL and release-ID inputs with explicit dimensions work without login.
screen publish <screen-id> <file> creates a new playlist, assigns it with an optional screen revision guard, reads back the assignment, and waits for the Player to show it. It does not update an existing playlist by name. Display names may repeat; use the playlist ID for an explicit playlist update. Its JSON result reports playlist_id, playlist_revision, screen_id, screen_revision, stage, assignment_verified, playback_verified, and playback.
The wait is bounded by --timeout (default 120000 ms) and polls every --poll-ms (default 2000 ms). It ends as soon as the Player acknowledges the playlist on glass: stage is playing and playback_verified is true. Otherwise stage stays assigned and playback.reason, repeated as a warning code with its next step, says why:
playback.reason | Meaning |
|---|---|
screen_offline | No Player is connected; it plays when the Player reconnects. |
playlist_not_effective | A takeover, campaign or schedule shows playback.effective_playlist_id; the published default plays when that ends. |
playback_failed | The Player reported a failed upgrade; playback.code names the cause. |
playback_pending | The wait ran out while downloading or preparing (playback.state). |
not_waited | --no-wait returned after assignment without waiting. |
A playback_partial warning means the playlist plays without playback.missing_page_count pages that do not fit the Player's storage.
When the project requires review for agent changes, or the session has Propose access, screen publish stops once the playlist or its assignment is proposed: stage is pending_review, the result names both reviews, and the envelope stays ok: true. Nothing plays until a person approves. Add --note TEXT to tell the reviewer what changed; see Reviews. Rerunning the identical publish waits again and never creates another playlist. --no-wait returns after assignment. While an iframe page shows, a screenshot of the Player web app is screenshot_unavailable (unsupported_surface); an application page is captured as the application renders itself.
Publishing saves a private local journal automatically. After an ambiguous failure, repeat the identical command and input with the same config to resume. If playlist creation succeeded before assignment failed, the error identifies the created playlist. Do not delete it or start another create to recover. A revision conflict requires inspecting the screen and reconciling the intended assignment; an already created playlist can be assigned explicitly with screen assign. Publishing never silently refreshes the expected revision. Unfinished recovery stops after the 24-hour server idempotency window; inspect and reconcile before making more writes.
To edit an existing playlist:
screenrig playlist show pl_EXISTING --output lobby.json
screenrig playlist update pl_EXISTING lobby.jsonplaylist show --output writes the editable document, {name, pages} plus the audio, format and fields the playlist has, and returns its path, playlist_id, and source revision on stdout. Optionally pass that revision with --expect-rev to guard the update. It preserves dynamic selectors, schedules, motion, and pinned application releases, removing server-derived and read-only fields, so the file validates and updates as written. Comments remain separate; page comments carry over by page ID. Plain playlist show is an inspection response; --editable without --output returns data.document, data.playlist_id, and data.revision. Updating a playlist affects every screen assigned to it. Under review, playlist update proposes the new document, and playlist show keeps returning the live version until a person approves it. To change part of a playlist, use playlist rename, playlist patch or playlist page add|replace|remove, which send only what changes.
K/V and comment writes accept --file - for stdin. Use playlist show ID --editable --human for the editable document on stdout. Application and playlist display names may repeat; use resource IDs for updates.
Replace one application release
After a successful app update, take data.application.release_id and identify the exact playlist, page, and application primitive to change. Preview the replacement:
screenrig playlist replace-release pl_EXISTING --page board-page --primitive board --release-id rel_NEWThis is a read-only impact review. Inspect data.previous_release_id, data.release_id, and data.affected_screens, including archived assignments. Apply directly with --apply. To opt into this impact check, also supply --expect-impact with the preview’s data.impact:
screenrig playlist replace-release pl_EXISTING --page board-page --primitive board --release-id rel_NEW --applyOther primitives and settings are preserved. The update affects every screen assigned to this shared playlist; archived screens retain the new pin for later use. When --expect-impact is supplied, a changed replacement, revision, or observed screen impact requires a fresh preview. Direct apply skips the screen survey; affected_screens is omitted. An already pinned release succeeds without writing. Assignments may change after the snapshot: the server checks the playlist revision atomically only when --expect-rev is supplied. The server validates release availability and ownership on apply. Existing pins remain unchanged until apply; afterward, verify manifest revisions and playback on the affected screens. Under review, --apply proposes the new pin; add --note TEXT for the reviewer.
playlist validate, create, update and patch, and screen publish, accept - as their
input file to read stdin, and playlist page add|replace accept --file -. JSON envelopes are never written into authored files. --expect-rev guards a revision. Omit the flag to write the current resource without a revision precondition. A supplied stale revision still returns revision_conflict.
Keep the path short
- Start with the official plugin
- Open a Player
- Choose an authoring path
- Install the official plugin
- See features
The bundled CLI uses api.screenrig.ai; Players use play.screenrig.ai; the dashboard is at screenrig.ai/dashboard; releases use isolated origins under apps.screenrig.ai. Application packages reach native Players through private, server-mediated delivery. The internal transport reference remains available for transport tooling.