Campaigns CLI commands

List the project's campaigns in the order screens read them.

campaign list

No parameters.

screenrig campaign list

data.items holds at most 100 campaigns, highest priority first and the newest first within a priority. Each carries the fields campaign show returns, with reach once it has been counted. A paused campaign is listed and applies nowhere. reserved marks a reserved campaign, and editable appears only for a caller limited to screen folders: false means the campaign reaches screens outside that scope.

Read one campaign.

campaign show <id>

screenrig campaign show cmp_LUNCH

Returns name, playlist_id, audience (the exact rule), priority, paused, reserved (true for a reserved campaign, which only a person who can approve changes), the from, until, windows, monthly, dates, except, data, interaction, covers, displays and start that are set, and revision, the value for --expect-rev on a later write. editable appears only for a caller limited to screen folders: false means the campaign reaches screens outside that scope and is read-only to that caller. import is present on a campaign a schedule import made. reach reports how many screens the audience matches: published when the campaign was last published (created, or updated with a new audience, playlist or paused state), current and at for the latest count, and empty_groups, the tag:NAME and folder:ID leaves of the audience that match no screen. A tag, folder, archive or delete that changes the count is recounted within about 15 seconds; campaign list carries reach too, and the reach_dropped and group_empty notifications watch it. An id from ads campaigns list answers not_found (exit 4) here.

Switch the screens of an audience to a playlist, always or while its rules hold.

campaign create --name NAME --playlist-id ID (--tag TAG | --any-tag TAG | --screen-id ID | --folder ID | --all-screens | --audience RULE) [--from TIME] [--until TIME] [--window SPEC] [--monthly SPEC] [--date SPEC] [--except DATES] [--data KEY[:PATH[=VALUE]]] [--on-touch [IDLE_S]] [--displays N[,N]] [--start on-time|next-item] [--covers WHERE] [--priority N] [--paused] [--note TEXT]

screenrig campaign create --name "Lunch menu" --playlist-id pl_LUNCH --tag north --window mon-fri@11:00-14:00
screenrig campaign create --name "North Tower welcome" --playlist-id pl_WELCOME --folder sfd_01EXAMPLEFOLDER000000000
screenrig campaign create --name "Holiday hours" --playlist-id pl_HOLIDAY --tag Lobby --from 2026-12-20T00:00 --until 2027-01-02T00:00 --priority 10
screenrig campaign create --name "North cafes" --playlist-id pl_CAFE --audience '{"all":[{"tag":"North"},{"any":[{"tag":"Cafe"},{"tag":"Patio"}]}]}' --paused
screenrig campaign create --name "Brunch" --playlist-id pl_BRUNCH --tag Cafe --monthly 1st-sun@10:00-14:00 --except 2026-12-06
screenrig campaign create --name "Touch to browse" --playlist-id pl_MENU --screen-id scr_KIOSK --on-touch 90
screenrig campaign create --name "Holiday opening" --playlist-id pl_HOLIDAY --tag Lobby --date 2026-12-24@18:00-22:00 --start on-time
screenrig campaign create --name "Wall outputs 1 and 2" --playlist-id pl_WALL --screen-id scr_WALL --displays 1,2
screenrig campaign create --name "Room availability" --playlist-id pl_LIVE --folder sfd_01EXAMPLEFOLDER000000000 --data "crd_ROOM:/available=true"
screenrig campaign create --name "Fire exits" --playlist-id pl_EXITS --folder sfd_01EXAMPLEFOLDER000000000 --note "Fire safety"

Tags are 1 to 32 letters or digits. DAYS is daily, a day (mon), a range (mon-fri; fri-mon wraps past the week's end) or a comma list (sat,sun). Without a time the window is the whole day, and an end at or before the start crosses midnight and belongs to the start day. In an --audience rule each member has exactly one of all, any, tag, screen_id or folder, groups nest at most 3 deep, an audience has at most 500 rules, and {"all":[]} is every screen. The server refuses a dead rule: an --except date outside --from and --until, a --date that starts outside them, and a --date that is also an exception (invalid_request, exit 8).

--data KEY holds while card data KEY exists, --data KEY:PATH while a value exists at the RFC 6901 pointer PATH, and --data KEY:PATH=VALUE while it equals VALUE, a JSON scalar (true, false, null, a number or a JSON-quoted string) or a bare string such as rain. Objects and arrays are refused. Missing or expired data never matches, and a present null or false counts as existing. KEY:=VALUE compares the whole document. Escape a colon in KEY as \:, and quote the argument to keep JSON string quotes: --data 'crd_ROOM:/status="true"'. The key {screen.weather} reads the weather at each screen's own location (screen update ID --location LAT,LON): --data '{screen.weather}:/condition=rain'.

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 campaign instead of creating another.

Change a campaign; the screens of its old and new audience re-resolve within a minute.

campaign update <id> [--name NAME] [--playlist-id ID] [audience option] [--from TIME | --clear-from] [--until TIME | --clear-until] [--window SPEC | --clear-windows] [--monthly SPEC | --clear-monthly] [--date SPEC | --clear-dates] [--except DATES | --clear-except] [--data KEY[:PATH[=VALUE]] | --clear-data] [--on-touch [IDLE_S] | --clear-on-touch] [--displays N[,N] | --clear-displays] [--start WHEN] [--covers WHERE] [--priority N] [--expect-rev REVISION] [--note TEXT]

screenrig campaign update cmp_LUNCH --playlist-id pl_LUNCH2 --expect-rev 2
screenrig campaign update cmp_LUNCH --tag Lobby --window sat,sun --priority 20
screenrig campaign update cmp_LUNCH --clear-until --clear-windows
screenrig campaign update cmp_BRUNCH --monthly 2nd-sun@10:00-14:00 --except 2026-12-13,2027-01-10
screenrig campaign update cmp_BROWSE --clear-on-touch --clear-displays
screenrig campaign update cmp_ROOMS --data crd_ROOM:/available=true
screenrig campaign update cmp_ROOMS --clear-data
screenrig campaign update cmp_LUNCH --playlist-id pl_LUNCH2 --note "Safety review done"

Pass at least one change; only the fields you pass change. A new --playlist-id is checked like create. After an interrupted or ambiguous request, rerun the identical command: it reuses the saved idempotency key, and the server returns the update that already happened instead of applying it again.

Stop a campaign on every screen without deleting it.

campaign pause <id> [--expect-rev REVISION] [--note TEXT]

screenrig campaign pause cmp_LUNCH
screenrig campaign pause cmp_LUNCH --note "Holiday over"

Screens that showed it return to what they would show without it within a minute. campaign resume starts it again.

Start a paused campaign again.

campaign resume <id> [--expect-rev REVISION] [--note TEXT]

screenrig campaign resume cmp_LUNCH
screenrig campaign resume cmp_LUNCH --note "Holiday again"

Every screen in the audience that the campaign can apply to switches to its playlist within a minute while the campaign holds.

Delete a campaign.

campaign delete <id> [--expect-rev REVISION] [--note TEXT]

screenrig campaign delete cmp_LUNCH
screenrig campaign delete cmp_LUNCH --note "Replaced by the winter campaign"

The campaign does not come back. Every screen showing it returns to what it would show without it within a minute; playlists, screens and tags stay. campaign pause stops a campaign and keeps it.

Show the screens a campaign reaches and how each stands.

campaign screens <id> [--limit N] [--cursor CURSOR]

screenrig campaign screens cmp_LUNCH

data.counts covers every live screen in the audience: audience, then one count per standing present. data.items is one page of those screens in screen id order, each with the campaign's status. data.next_cursor is absent on the last page. On a screen whose Player resolves its own stack, the standing is where that stack puts the campaign: a strip or main campaign plays in its region and a --displays campaign on its displays.

Show why each campaign plays on one screen or not, now or at a chosen time.

campaign explain <screen-id> [--at TIME] [--to TIME]

screenrig campaign explain scr_LOBBY
screenrig campaign explain scr_LOBBY --at 2026-12-24T18:00 --to 2026-12-26T00:00

data.items lists every campaign of the project in the order the screen reads them, each with a standing from campaign screens or not_in_audience; a blocked row names the fix. data.effective_playlist is the playlist the screen plays now (id, source, which is takeover, campaign, schedule, default or folder, and entry_id, the campaign, schedule entry or folder id), or null when the screen shows no playlist. It changes nothing.

With --at, data.at holds the answer for that time: instant, timezone (the screen's effective timezone) and local (the instant on the screen's clock), effective_playlist (its until is the next change) and a verdicts row for the takeover, every campaign and every schedule entry, in the order the screen reads them.

A verdict is won (the playlist shown), outranked (it holds, and by names the winner), not_started (before its start), ended (past its end), outside_hours (inside its dates, outside its windows, monthly rules or dates, or on an exception date; next_start says when it holds again within eight days), conditional (it holds by time and plays while someone is using the screen, reason interaction, or while its data condition holds, reason data) or off (it does not apply, and reason says why: paused, not_in_audience, no_default_playlist, playlist_unavailable, region_not_laid_out or stack_only). On a screen whose Player resolves its own stack, the verdicts read that stack: a strip or main level wins or is outranked in its region, and a display lock on its displays. effective_playlist and the timeline stay the page on display 1, and data.at.not_judged lists player_stack.

--to adds data.at.timeline, the spans in which the playlist does not change, and timeline_truncated marks an answer that stopped before --to: ask again with --at set to the last span's to. data.at.not_judged says what is not judged: the takeover, schedule and campaigns are read as they are now, and data.items stays the state now.

Show what creating or changing a campaign would do before making it.

campaign preview [<id>] [--name NAME] [--playlist-id ID] [audience option] [rule flags] [clear flag] [--paused | --publish] [--calendar-from INSTANT] [--calendar-to INSTANT]

screenrig campaign preview cmp_LUNCH --tag Lobby
screenrig campaign preview cmp_LUNCH --clear-until --priority 20
screenrig campaign preview cmp_LUNCH --publish --folder sfd_TEST
screenrig campaign preview cmp_LUNCH --publish --calendar-from 2026-12-01T00:00:00Z --calendar-to 2027-01-01T00:00:00Z
screenrig campaign preview --name "Holiday hours" --playlist-id pl_HOLIDAY --tag Lobby --from 2026-12-20T00:00 --until 2027-01-02T00:00

The flags are checked as the write checks them, so a preview refuses what the write refuses. With an <id>, pass at least one change: a campaign update flag, --paused or --publish. Nothing is written. data.gained and data.lost are {count, screen_ids} (the first 500 by id): the screens that would carry the campaign and do not now, and those that would no longer carry it. A paused campaign is on no screen, so publishing one gains its audience; an edit that keeps a screen's campaign shows in the calendars alone. data.calendar.before and data.calendar.after are the schedule calendars over --calendar-from to --calendar-to for the screens of the old and the new audience, with drafts drawn as paused levels. --human prints the first display's stretches and the drafts that would hold, and says when the calendar does not change.

Unpause a draft campaign, optionally only to a test folder or a few test screens.

campaign publish <id> [--test-folder ID | --test-screen ID] [--expect-rev REVISION]

screenrig campaign publish cmp_LUNCH
screenrig campaign publish cmp_LUNCH --test-folder sfd_TEST
screenrig campaign publish cmp_LUNCH --test-screen scr_LOBBY,scr_CAFE --expect-rev 2

A draft is a paused campaign: it is on no screen until it is published. Without a test option the campaign reaches its own audience within a minute. A test option replaces the audience in the same write, so only the test screens switch. The usual flow: campaign create --paused with the real audience, campaign publish ID --test-folder FOLDER, look at the test screens, then campaign promote ID --revision N. campaign preview ID --publish shows the effect first.

Put a draft's audience on the campaign after its test.

campaign promote <id> --revision N [--expect-rev REVISION]

screenrig campaign promote cmp_LUNCH --revision 1
screenrig campaign promote cmp_LUNCH --revision 1 --expect-rev 2

The audience of revision N becomes the campaign's in one write, a new revision whose change is promoted, and every screen of the old and the new audience re-resolves within a minute. Revision N must be a paused revision (invalid_request names it otherwise), and the campaign must be live: a campaign that is paused now has no test to promote. A revision whose audience is already the campaign's changes nothing. --expect-rev is the campaign's current revision, not N. Promote needs the access campaign update needs.

List a campaign's revisions, newest first.

campaign revisions <id> [--after CURSOR]

screenrig campaign revisions cmp_LUNCH
screenrig campaign revisions cmp_LUNCH --after CURSOR

data.items holds at most 50 revisions, each with revision, created_at, change, current, author when known and campaign, the campaign as it was after that write, with its paused state. change is created, edited (an update or a schedule import), restored or promoted (a copy of the earlier revision it names in restored_from), or baseline, the revision the campaign held when its history began. A campaign whose history has no unpaused revision is a draft. While data.next_cursor is a string, older revisions remain: run the command again with --after set to it. Revisions are kept as long as the campaign is and go when it is deleted. Read only access is enough.

Make an earlier revision current again by copying it forward.

campaign restore <id> --revision N [--expect-rev REVISION]

screenrig campaign restore cmp_LUNCH --revision 3
screenrig campaign restore cmp_LUNCH --revision 3 --expect-rev 5

The name, playlist, audience, rules, region, priority and paused state of revision N become a new revision whose change is restored, checked as campaign update is checked: its playlist must still exist and be approved (playlist_not_approved, exit 5). Every screen of the old and the new audience re-resolves within a minute. Earlier revisions stay as they were, and restoring the current content changes nothing. Restore needs the access campaign update needs.