Informes: comandos CLI

Listar los tipos de informe y los filtros de cada uno.

reports list

Sin parámetros.

screenrig reports list

Devuelve data.items, cada uno con el kind, el title, la description del informe y los filtros que acepta (params), además de los formats de archivo.

Generar un informe como filas, o escribirlo en un archivo CSV, XLSX o PDF.

reports show <kind> [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--group-by folder|screen|tag]
    [--folder-id ID [--direct]] [--tag TAG] [--campaign-id ID] [--advertiser NAME]
    [--format json|csv|xlsx|pdf] [--output FILE]

screenrig reports show fleet_health --group-by screen --from 2026-10-01 --to 2026-10-28
screenrig reports show proof_of_play --advertiser "Acme Corp" --format pdf --output acme-proof-of-play.pdf

JSON devuelve data.columns, data.rows, data.totals y data.notes; las filas de un informe por carpetas llevan id, parent_id y depth para el esquema, y su primera fila es el proyecto entero. Un archivo responde con su ruta, bytes y SHA-256. Un informe paginado se escribe completo, hasta 50000 filas (data.truncated en caso contrario). proof_of_play necesita un proyecto que venda tiempo publicitario en sus propias pantallas. Basta el acceso Solo lectura con la capacidad reports.

Enviar un informe por correo a los miembros del proyecto según una programación.

reports subscriptions list
reports subscriptions show <id>
reports subscriptions create --name NAME --kind KIND --format pdf|xlsx|csv
    --recipients MEMBERS --cadence daily|weekly|monthly [--weekday DAY]
    [--day-of-month N] [--hour N] [--timezone ZONE] [--filter NAME=VALUE]
reports subscriptions update <id> [--name NAME] [--format pdf|xlsx|csv]
    [--recipients MEMBERS] [--filter NAME=VALUE] [--cadence daily|weekly|monthly]
    [--weekday DAY] [--day-of-month N] [--hour N] [--timezone ZONE]
    [--pause | --resume] [--expect-rev REVISION]
reports subscriptions delete <id>
reports subscriptions send <id>

screenrig reports subscriptions create --name "Monday fleet health" --kind fleet_health --cadence weekly --weekday monday --hour 7 --timezone America/Los_Angeles --format pdf --recipients ann@example.com,usr_01EXAMPLEPERSON0000
screenrig reports subscriptions update rsub_01EXAMPLESUB0000000000 --pause

Cada ejecución cubre el período anterior a ella en días UTC: ayer, los siete días anteriores o el mes pasado. Los destinatarios deben ser miembros del proyecto, y un miembro que se va deja de recibir el informe. update necesita al menos un cambio. send envía el informe ahora por el período que cubriría una ejecución ahora, sin mover la programación, y responde con la suscripción, incluidos last_status y last_error de este envío. Una ejecución fallida se reintenta y aparece como last_status failed con last_error; un adjunto PDF o XLSX de más de 8 MiB no se envía. Una organización tiene como máximo 50 suscripciones entre sus proyectos. Leer requiere la capacidad project y acceso Solo lectura; crear, cambiar, eliminar y enviar requieren acceso Administrar.

Listar las entradas de auditoría, las más recientes primero.

audit list [--actor ID] [--actor-kind KIND] [--source SOURCE] [--resource-type TYPE]
    [--resource-id ID] [--action CODE] [--field POINTER] [--since TIME] [--until TIME]
    [--limit N] [--after CURSOR]

screenrig audit list --resource-type screen --resource-id scr_01EXAMPLESCREEN00000000
screenrig audit list --action 'playlist.*' --source cli --limit 20

Devuelve data.items de más reciente a más antiguo, cada uno con actor (kind, id, name), source, action, resource (type, id, name) y changes, cada uno con un path (un puntero JSON dentro del recurso), before y after; una credencial aparece como (redacted) en ambos lados. seq y hash aparecen cuando una entrada se encadena, en cuestión de segundos. data.next_cursor es null en la última página. Basta el acceso Solo lectura con la capacidad project.

Mostrar una entrada de auditoría con el antes y el después de cada campo modificado.

audit show <id>

screenrig audit show aud_01EXAMPLEENTRY0000000000

Devuelve la entrada con path, before y after de cada campo modificado, quién hizo el cambio y por qué vía, y su lugar en la cadena una vez encadenada.

Mostrar la cabecera de la cadena de auditoría para conservarla como ancla.

audit head

Sin parámetros.

screenrig audit head

Imprime la última entrada encadenada como SEQ:HASH, el límite de retención desde el que empieza la cadena y cuántas entradas esperan a ser encadenadas. Conserve la cabecera: audit verify --anchor SEQ:HASH demuestra más adelante que el historial no se reescribió ni se truncó.

Recalcular la cadena de hashes de auditoría e informar de todo lo que no coincida.

audit verify [--from-seq N] [--limit N] [--anchor SEQ:HASH]

screenrig audit verify --anchor 128:3f2c0b6e9a4d81c7f5e0a2b4c6d8e0f1a3b5c7d9e1f30415263748596a7b8c9d

Informa de hash_mismatch, prev_mismatch, gap, head_mismatch, anchor_mismatch o floor_mismatch por entrada en data.problems. Termina con el código 13 y data.ok false cuando la cadena no se verifica; data.next_seq continúa una cadena más larga.

Escribir el registro de auditoría filtrado en un archivo CSV, XLSX o PDF.

audit export --format csv|xlsx|pdf [--output FILE]
    [--actor ID] [--actor-kind KIND] [--source SOURCE] [--resource-type TYPE]
    [--resource-id ID] [--action CODE] [--field POINTER] [--since TIME] [--until TIME]

screenrig audit export --format csv --output audit.csv
screenrig audit export --format pdf --resource-type playlist --output playlist-changes.pdf

Escribe una fila por campo modificado, de la más antigua a la más reciente, hasta 50000 filas (data.truncated en caso contrario), con la cabecera de la cadena y el límite de retención en el archivo, y responde con su ruta, bytes y SHA-256.

Leer registros por reproducción, una fila por inicio visible.

playback plays [--from TIME] [--to TIME] [--screen-id ID] [--media-id ID] [--tag TAG] [--cursor CURSOR] [--limit N] [--all]
playback plays --format csv|xlsx|pdf [--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
screenrig playback plays --format xlsx --from 7d --tag Lobby --output lobby-plays.xlsx

El CLI normaliza ambos límites a UTC y los envía en cada solicitud; data.from y data.to los reflejan. Los últimos 5 segundos se retienen hasta estabilizarse, por lo que una reproducción aparece unos 5 segundos después de recibirse, y data.to informa ese fin efectivo. Una reproducción de aplicación lleva release_id y un media_id vacío. JSON devuelve una página en data.items con data.next_cursor, y data.next.argv es el comando exacto para la siguiente página. --all se detiene antes de tiempo, con data.next y una advertencia, al llegar al límite de páginas (playback_plays_truncated) o cuando se agota el presupuesto de exportación (playback_export_rate_limited), en lugar de gastar solicitudes hasta un rechazo.

El CSV cumple RFC 4180 con la fila fija de encabezado screen_id,playlist_id,page_id,primitive_id,media_id,primitive,started_at,received_at,manifest_revision,playlist_revision, tiempos en RFC 3339 UTC. primitive_id y started_at están vacíos a menos que el Player los haya reportado. Una celda que comienza con =, +, -, @, tabulación o retorno de carro lleva un ' inicial para que las hojas de cálculo no lo evalúen. El CLI escribe a través de un archivo temporal privado en el mismo directorio y reemplaza un archivo existente solo después de que la transmisión termina correctamente. --timeout es el límite sin progreso para la transmisión, 60000 ms sin un byte por defecto, no un límite en su duración total. El sobre informa path, bytes, rows, sha256, content_type, from, to y last_received_at; el CSV nunca entra en el sobre. Con --output - el CSV va a stdout y no se imprime ningún sobre.

Si una transmisión falla a mitad de camino, el comando sale con código distinto de cero y nunca escribe el archivo destino. Las filas completas ya recibidas permanecen en FILE.partial (FILE.partial-2 y siguientes si ese ya existe), y error.next exporta el resto del rango desde el último received_at a un FILE-rest.csv no usado. Las filas recibidas en ese instante exacto aparecen en ambos, así que elimine los duplicados al unirlos. Con --output - el CSV incompleto permanece en stdout, y el error y el comando next van a stderr.

xlsx y pdf se generan en el servidor y se guardan del mismo modo, mediante un archivo temporal privado. El sobre informa path, bytes, sha256, content_type y format, y el archivo contiene las primeras 50,000 filas del rango.

Lea totales diarios de reproducción para este proyecto, días más recientes primero.

playback list [--screen-id ID] [--media-id ID] [--day YYYY-MM-DD | --day-from YYYY-MM-DD --day-to YYYY-MM-DD]
              [--format json|csv|xlsx|pdf] [--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
screenrig playback list --format pdf --day-from 2026-09-01 --day-to 2026-09-30 --output september.pdf

Una fila por pantalla, objeto multimedia y día UTC. Los filtros seleccionan las filas propias de quien llama. JSON devuelve como máximo 200 filas en data.items, primero el día más reciente; los totales diarios se actualizan cada 10 minutos aproximadamente, y playback plays muestra inicios más recientes. La fila de encabezado del CSV es screen_id,media_id,filename,primitive,day,play_count,last_page_id,last_manifest_revision,first_started_at,last_started_at. El CSV es una solicitud escrita como un CSV de reproducciones, y su respuesta informa path, bytes, rows, sha256 y content_type; una respuesta xlsx o pdf informa path, bytes, sha256, content_type y format. Una exportación diaria fallida no conserva nada; vuelva a ejecutarla.

Leer conteos de reproducción por día UTC, o clasificar las pantallas o medios más activos.

playback totals [--by day|screen|media|screen_day] [--day-from YYYY-MM-DD] [--day-to YYYY-MM-DD]
                [--screen-id ID | --media-id ID] [--top N] [--format json|csv|xlsx|pdf] [--output FILE]

screenrig playback totals
screenrig playback totals --day-from 2026-09-01 --day-to 2026-09-30 --screen-id scr_01EXAMPLESCREEN00000000
screenrig playback totals --by screen --top 5
screenrig playback totals --by media --day-from 2026-09-01 --day-to 2026-09-30
screenrig playback totals --by screen_day --top 3
screenrig playback totals --by screen --top 10 --format xlsx --output busiest-screens.xlsx

Los conteos provienen de los resúmenes diarios, que siguen la ingestión hasta unos 21 minutos; playback plays muestra inicios más recientes. day responde data.days, screen y media responden data.screens y data.media, y screen_day responde data.screen_days. Una serie diaria abarca como máximo 366 días (92 con --screen-id o --media-id) y un ranking como máximo 92. data.truncated es true cuando un ranking sobre una ventana demasiado grande para una lectura mantuvo solo las mejores claves de cada segmento. Un formato de archivo escribe el archivo del servidor en --output, y su sobre informa path, bytes, sha256, content_type y format.

Lee cuántas de las reproducciones numeradas por los Players llegaron a screenRIG por día UTC, y los huecos donde faltaron reproducciones.

playback completeness [--day-from YYYY-MM-DD] [--day-to YYYY-MM-DD] [--screen-id ID] [--limit N]
                      [--format json|csv|xlsx|pdf] [--output FILE]

screenrig playback completeness
screenrig playback completeness --day-from 2026-09-01 --day-to 2026-09-30
screenrig playback completeness --screen-id scr_01EXAMPLESCREEN00000000 --limit 20
screenrig playback completeness --format pdf --output completeness.pdf

Cada inicio de un medio lleva un número, así que una reproducción que una pantalla realizó y nunca se entregó, como la realizada sin conexión más allá de su cola de informes de 24 horas, deja un hueco. data.completeness es data.measured_plays sobre data.measured_plays más data.missing_plays en la ventana, de 0 a 1, y null cuando no se midió ninguno: las reproducciones sin número, de Players que no numeran sus reproducciones o de antes de que lo hicieran, no se miden. data.days da las mismas tres cifras para cada día UTC que tenga alguna, de la más antigua a la más reciente, y un hueco se cuenta en el día de la reproducción posterior. data.gaps lista cada hueco del más reciente al más antiguo con screen_id, day, from y to (las horas de inicio de las reproducciones a cada lado) y missing_plays; --limit lo limita, y data.truncated es true cuando existen más. Una pantalla apagada no realiza reproducciones y no deja huecos. El resumen se actualiza cada 10 minutos. Una solicitud API medida; no se aplica el presupuesto de exportación de reproducción. Un formato de archivo escribe el archivo del servidor en --output, y su sobre informa path, bytes, sha256, content_type y format.