Campañas: comandos CLI

Listar las campañas del proyecto en el orden en que las pantallas las leen.

campaign list

Sin parámetros.

screenrig campaign list

data.items contiene como máximo 100 campañas, las de mayor prioridad primero y, dentro de una misma prioridad, las más nuevas primero. Cada una lleva los campos que devuelve campaign show, con reach una vez contada. Una campaña pausada aparece en la lista y no se aplica en ninguna parte. reserved marca una campaña reservada, y editable aparece solo para un solicitante limitado a carpetas de pantallas: false significa que la campaña alcanza pantallas fuera de ese alcance.

Lea una campaña.

campaign show <id>

screenrig campaign show cmp_LUNCH

Devuelve name, playlist_id, audience (la regla exacta), priority, paused, reserved (true para una campaña reservada, que solo cambia una persona que puede aprobar), los from, until, windows, monthly, dates, except, data, interaction, covers, displays y start que están establecidos, y revision, el valor para --expect-rev en una escritura posterior. editable aparece solo para un solicitante limitado a carpetas de pantallas: false significa que la campaña alcanza pantallas fuera de ese alcance y es de solo lectura para ese solicitante. import está presente en una campaña creada por una importación de programación. reach informa cuántas pantallas coinciden con la audiencia: published cuando la campaña se publicó por última vez (creada, o actualizada con una nueva audiencia, lista de reproducción o estado de pausa), current y at para el recuento más reciente, y empty_groups, las hojas tag:NAME y folder:ID de la audiencia que no coinciden con ninguna pantalla. Una etiqueta, carpeta, archivo o eliminación que cambia el recuento se vuelve a contar en unos 15 segundos; campaign list también lleva reach, y las notificaciones reach_dropped y group_empty lo vigilan. Un id de ads campaigns list responde not_found (salida 4) aquí.

Cambiar las pantallas de una audiencia a una lista de reproducción, siempre o mientras rigen sus reglas.

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"

Las etiquetas tienen de 1 a 32 letras o dígitos. DAYS es daily, un día (mon), un rango (mon-fri; fri-mon cruza el final de la semana) o una lista separada por comas (sat,sun). Sin hora, la ventana es todo el día, y un fin igual o anterior al inicio cruza la medianoche y pertenece al día de inicio. En una regla --audience cada miembro tiene exactamente uno de all, any, tag, screen_id o folder, los grupos se anidan hasta 3 niveles de profundidad, una audiencia tiene como máximo 500 reglas y {"all":[]} equivale a todas las pantallas. El servidor rechaza una regla muerta: una fecha --except fuera de --from y --until, un --date que empieza fuera de ellas y un --date que también es una excepción (invalid_request, salida 8).

--data KEY se cumple mientras existan los datos de tarjeta KEY, --data KEY:PATH mientras exista un valor en el puntero RFC 6901 PATH, y --data KEY:PATH=VALUE mientras sea igual a VALUE, un escalar JSON (true, false, null, un número o una cadena entre comillas JSON) o una cadena simple como rain. Los objetos y los arreglos se rechazan. Los datos ausentes o caducados nunca coinciden, y un null o un false presente cuenta como existente. KEY:=VALUE compara el documento completo. Escape los dos puntos en KEY como \: y ponga el argumento entre comillas para conservar las comillas de la cadena JSON: --data 'crd_ROOM:/status="true"'. La clave {screen.weather} lee el clima en la ubicación de cada pantalla (screen update ID --location LAT,LON): --data '{screen.weather}:/condition=rain'.

Después de una creación interrumpida o ambigua, vuelva a ejecutar el mismo comando dentro de 24 horas: reutiliza la clave de idempotencia guardada, y el servidor devuelve la misma campaña en lugar de crear otra.

Cambiar una campaña; las pantallas de su audiencia anterior y de la nueva se vuelven a resolver dentro de un minuto.

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"

Pase al menos un cambio; solo cambian los campos que pase. Un --playlist-id nuevo se verifica como al crear. Después de una solicitud interrumpida o ambigua, vuelva a ejecutar el mismo comando: reutiliza la clave de idempotencia guardada, y el servidor devuelve la actualización que ya ocurrió en lugar de aplicarla de nuevo.

Detener una campaña en todas las pantallas sin eliminarla.

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

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

Las pantallas que la mostraban vuelven a lo que mostrarían sin ella dentro de un minuto. campaign resume la inicia de nuevo.

Iniciar de nuevo una campaña pausada.

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

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

Cada pantalla de la audiencia a la que la campaña puede aplicarse cambia a su lista de reproducción dentro de un minuto mientras la campaña rige.

Eliminar una campaña.

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

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

La campaña no regresa. Cada pantalla que la muestra vuelve a lo que mostraría sin ella dentro de un minuto; las listas de reproducción, las pantallas y las etiquetas permanecen. campaign pause detiene una campaña y la conserva.

Mostrar las pantallas que alcanza una campaña y el estado de cada una.

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

screenrig campaign screens cmp_LUNCH

data.counts cubre cada pantalla en vivo de la audiencia: audience, luego un conteo por cada estado presente. data.items es una página de esas pantallas en orden de id de pantalla, cada una con el status de la campaña. data.next_cursor está ausente en la última página. En una pantalla cuyo Player resuelve su propia pila, el estado es el que esa pila da a la campaña: una campaña de franja o main se reproduce en su región, y una campaña --displays, en sus pantallas.

Mostrar por qué cada campaña se reproduce o no en una pantalla, ahora o en un momento elegido.

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 lista todas las campañas del proyecto en el orden en que la pantalla las lee, cada una con un estado de campaign screens o not_in_audience; una fila blocked nombra la solución. data.effective_playlist es la lista de reproducción que la pantalla reproduce ahora (id, source, que es takeover, campaign, schedule, default o folder, y entry_id, el id de la campaña, de la entrada de programación o de la carpeta), o null cuando la pantalla no muestra ninguna lista de reproducción. No cambia nada.

Con --at, data.at contiene la respuesta para ese momento: instant, timezone (la zona horaria efectiva de la pantalla) y local (el instante en el reloj de la pantalla), effective_playlist (cuyo until es el siguiente cambio) y una fila verdicts para la toma de control, cada campaña y cada entrada de programación, en el orden en que la pantalla las lee.

Un veredicto es won (la lista de reproducción mostrada), outranked (rige, y by nombra a la ganadora), not_started (antes de su inicio), ended (después de su fin), outside_hours (dentro de sus fechas, fuera de sus ventanas, reglas mensuales o fechas, o en una fecha de excepción; next_start indica cuándo vuelve a regir en los próximos ocho días), conditional (rige por horario y se reproduce mientras alguien usa la pantalla, reason interaction, o mientras se cumple su condición de datos, reason data) o off (no se aplica, y reason dice por qué: paused, not_in_audience, no_default_playlist, playlist_unavailable, region_not_laid_out o stack_only). En una pantalla cuyo Player resuelve su propia pila, los veredictos leen esa pila: un nivel de franja o main gana o queda superado en su región, y un bloqueo de pantallas, en sus pantallas. effective_playlist y la línea de tiempo siguen siendo la página de la pantalla 1, y data.at.not_judged incluye player_stack.

--to añade data.at.timeline, los tramos en los que la lista de reproducción no cambia, y timeline_truncated marca una respuesta que se detuvo antes de --to: vuelva a consultar con --at establecido en el to del último tramo. data.at.not_judged indica lo que no se juzga: la toma de control, el horario y las campañas se leen tal como están ahora, y data.items sigue siendo el estado actual.

Mostrar qué haría crear o cambiar una campaña antes de hacerlo.

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

Las opciones se comprueban como las comprueba la escritura, así que una vista previa rechaza lo que rechaza la escritura. Con un <id>, pase al menos un cambio: una opción de campaign update, --paused o --publish. No se escribe nada. data.gained y data.lost son {count, screen_ids} (los primeros 500 por id): las pantallas que llevarían la campaña y ahora no, y las que dejarían de llevarla. Una campaña en pausa no está en ninguna pantalla, así que publicarla gana su audiencia; una edición que mantiene la campaña en una pantalla solo se ve en los calendarios. data.calendar.before y data.calendar.after son los calendarios de horarios entre --calendar-from y --calendar-to para las pantallas de la audiencia antigua y de la nueva, con los borradores dibujados como niveles en pausa. --human imprime los tramos de la primera pantalla y los borradores que regirían, y avisa cuando el calendario no cambia.

Quitar la pausa a una campaña en borrador, si se desea solo para una carpeta de prueba o unas pocas pantallas de prueba.

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

Un borrador es una campaña en pausa: no está en ninguna pantalla hasta que se publica. Sin opción de prueba, la campaña llega a su propia audiencia en un minuto. Una opción de prueba reemplaza la audiencia en la misma escritura, de modo que solo cambian las pantallas de prueba. El flujo habitual: campaign create --paused con la audiencia real, campaign publish ID --test-folder FOLDER, mirar las pantallas de prueba y luego campaign promote ID --revision N. campaign preview ID --publish muestra antes el efecto.

Poner la audiencia de un borrador en la campaña después de su prueba.

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

La audiencia de la revisión N pasa a ser la de la campaña en una escritura, una revisión nueva cuyo change es promoted, y cada pantalla de la audiencia antigua y de la nueva se vuelve a resolver en un minuto. La revisión N debe ser una revisión en pausa (invalid_request la nombra en caso contrario), y la campaña debe estar activa: una campaña en pausa ahora no tiene prueba que promover. Una revisión cuya audiencia ya es la de la campaña no cambia nada. --expect-rev es la revisión actual de la campaña, no N. Promover requiere el acceso que requiere campaign update.

Listar las revisiones de una campaña, la más reciente primero.

campaign revisions <id> [--after CURSOR]

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

data.items contiene como máximo 50 revisiones, cada una con revision, created_at, change, current, author cuando se conoce y campaign, la campaña tal como quedó después de esa escritura, con su estado de pausa. change es created, edited (una actualización o una importación de programación), restored o promoted (una copia de la revisión anterior que nombra restored_from), o baseline, la revisión que tenía la campaña cuando empezó su historial. Una campaña cuyo historial no tiene ninguna revisión sin pausar es un borrador. Mientras data.next_cursor sea una cadena, quedan revisiones más antiguas: ejecute el comando de nuevo con --after establecido en ese valor. Las revisiones se conservan mientras exista la campaña y se van con su eliminación. Basta con acceso de solo lectura.

Hacer actual de nuevo una revisión anterior copiándola hacia delante.

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

El nombre, la lista de reproducción, la audiencia, las reglas, la región, la prioridad y el estado de pausa de la revisión N pasan a ser una revisión nueva cuyo change es restored, comprobada como se comprueba campaign update: su lista de reproducción debe seguir existiendo y estar aprobada (playlist_not_approved, salida 5). Cada pantalla de la audiencia antigua y de la nueva se vuelve a resolver en un minuto. Las revisiones anteriores quedan como estaban, y restaurar el contenido actual no cambia nada. Restaurar requiere el acceso que requiere campaign update.