screenRIG
登录开始使用

文档

屏幕 CLI 命令

配对、列出、发布到、分配、打标签、移动、重新加载、截取和删除屏幕，并管理文件夹、链接、视频墙和实时画面。

这里的每个命令都按 CLI 参考所述运行：全局标志、JSON 输出、退出代码、修订和重试。

屏幕

屏幕即一个播放器。这些命令读取它，指向播放列表，并管理其生命周期。写入时修订前提可选。

标签将屏幕分组为设备群。每个屏幕携带 0 到 16 个唯一标签，标签由 1 到 32 个字母或数字组成，通过 screen tag 设置。screen assign、screen reload、screen toast、screen tag 和 screen screenshot 接受一个或多个屏幕 ID，或 --tag TAG，设备群响应报告所有屏幕：见 设备群结果。

屏幕文件夹按地点对屏幕分组，每个屏幕一个文件夹。设备组命令也接受 --folder ID：见 屏幕文件夹。

受保护文件夹中的屏幕对播放列表更改返回 pending_review，等待第二位审批人决定；对标签、字段、位置、时区、视频墙、替换、删除、归档、暂停、显示器、音量、提示和页面播放的更改，则以 protected_target（退出码 5）拒绝。

screen list、screen show、screen update、screen assign 或 screen publish 上出现警告 storage_full，表示运行播放器的设备没有足够空间存放其内容：请先释放该设备的存储空间，然后重试。

screen pair#

使用 Player 屏幕上显示的代码将其配对。

screen pair <code...> [--name NAME] [--folder ID]
参数类型必填默认备注
<code...>string是无播放器显示的六字符配对码。空格、连字符和字母大小写都会被忽略，所以分两组显示的配对码，加不加引号都可以使用。
--name NAMEstring否未被使用的 Screen N屏幕的显示名称，1 到 120 个字符。
--folder IDstring否项目根目录要放入该屏幕的 sfd_ 屏幕文件夹。仅限屏幕文件夹的智能体必须指定其范围内的文件夹；项目根目录和其他所有文件夹都会返回 outside_screen_scope（退出码 3）。
screenrig screen pair "$PAIRING_CODE" --name "Lobby"
screenrig screen pair "$PAIRING_CODE" --folder sfd_01EXAMPLEFOLDER000000000

响应包含 public_url 和已配对的 screen。播放器在下次联系服务时完成配对，显示器上无需任何操作：完成后 screen show 会报告 state active 和 online true。请求中断后，重新运行相同命令即可复用已保存的幂等键。

browser setup#

使用浏览器播放器显示的代码完成其设置。

browser setup --code CODE [--open]
参数类型必填默认备注
--code CODEstring是无浏览器播放器显示的设置代码。
--openboolean否关闭打开浏览器播放器。
screenrig browser setup --code SETUP_CODE --open

响应包含 code、status（claimed）、screen_id 以及屏幕的 player_public_url。CLI 会隐藏未通过安全检查的 URL，并给出警告 player_url_withheld。无效或过期的代码不会创建屏幕。请求中断后，请重新运行相同的命令。

screen list#

列出屏幕。除非请求，否则不包含归档屏幕。

screen list [--state archived] [--tag TAG] [--folder ID|root] [--field NAME=VALUE...] [--near LAT,LON,KM]
参数类型必填默认备注
--statestring否活跃屏幕唯一接受的值是archived，仅列出已归档的屏幕。
--tag TAGstring否每个屏幕仅列出带有此精确标签的屏幕。
--folder ID|rootstring否每个屏幕仅此 sfd_ 屏幕文件夹内直接包含的屏幕，不含其子文件夹中的屏幕，或带 root 时仅不在任何文件夹中的屏幕。
--field NAME=VALUEstring否无仅列出字段 NAME 的值恰好为 VALUE 的屏幕。可重复使用，每个名称只能出现一次；屏幕必须匹配所有条件。
--near LAT,LON,KMstring否无仅列出位于该点（十进制度数）KM 公里范围内的屏幕；KM 须大于 0。没有位置的屏幕会被排除。
screenrig screen list --tag Lobby
screenrig screen list --folder sfd_01EXAMPLEFOLDER000000000
screenrig screen list --field region=north
screenrig screen list --near 47.6062,-122.3321,25

这些过滤器可以组合使用。每一行在屏幕具备时会包含 tags、folder_id、fields 和 location。使用 --human 时，只有当列出的屏幕有相应值，表格才会增加对应的列：PLATFORM、REASON（已归档屏幕的 archive_reason）、TAGS、FOLDER、FIELDS、LOCATION、ASSIGNED（播放的不是默认播放列表的屏幕）、HEALTH（需要关注的屏幕）和 UPGRADE（其播放器仍在切换到所下发的播放列表版本，或切换失败的屏幕）。--state archived 还会列出由播放器自行归档的屏幕（device_reset、device_unpair）以及被 screen replace 归档的屏幕（replaced）。

screen show#

读取一个屏幕，包括版本、分配和在线状态。

screen show <id>
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
screenrig screen show scr_01EXAMPLESCREEN00000000

tags 列出屏幕的车队标签。effective_playlist、takeover 和 playlist_schedule 报告屏幕播放内容及原因；见 计划和接管。health 和播放器的主机能力见 设备健康和电源。online 为真时表示播放器已连接，包括短暂重连窗口。可选的 last_online_at 和 last_ip 在首次连接后出现。可选的 observation 报告播放器绘制的表面：id、width、height、pixel_ratio 和 presentation。以上均为只读；screen update 无法发送它们，归档屏幕仍返回其行。

commands 列出屏幕最近 10 次重启、重新加载、清除缓存、应用重启和更新，最早的在前，每条包含其 type、其 state（queued、sent、done、failed、expired、cancelled 或 superseded）、其 source（由重启排程发出的重启为 schedule；由人工请求的则没有）、其 expires_at，以及发送或完成的时间。reboot_schedule 和 next_reboot_at 报告屏幕的重启排程和下一个重启窗口的开始时间。播放器结束的清除缓存、应用重启或更新还会携带其 cause 和一条简短的 detail，--human 会将其打印为 CAUSE 列以及表格下方的一行。suspension 携带已暂停屏幕的 message 和 since。被 screen replace 归档的屏幕会报告 replaced_by，即其设备迁移到的屏幕。使用 --human 时，screen show 会打印其中每一项。

last_outage 报告屏幕最近一次中断：offline_since、back_at 和 duration_s，并在健康报告做出判定后给出 likely_cause，其值为 device_restart、app_crash、app_restart、network 或 platform；screenRIG 无法判断时则不出现。重启会在屏幕恢复时判定，而网络或 screenRIG 原因要等 Player 的下一份健康报告，最长可能需要十五分钟。glass 携带 screenRIG 根据屏幕的播放报告和截图得出的判定。使用 --human 时，screen show 会输出 Last outage 和 Likely cause，并在判定发现问题时输出 Playlist stalled、Blank screen 或 Frozen picture；这些判定不涉及的内容见通知。

folder_id 表示屏幕所在的文件夹，位于项目根目录时不存在。fields、location 和 wall 在设置后出现：参见 screen update 和 screen wall set。播放器能读取时，observation.surfaces 的每个条目还包含 rotation；视频墙每个输出报告一个条目，名称即 screen wall set 所接受的名称。

manifest_upgrade 报告播放器是否已切换到下发给它的播放列表版本。其 state 为 none、pending、downloading、preparing、activating、retrying、failed、blocked、partial 或 current，并附有 desired_playlist 和 active_playlist（id、name 和 revision），即播放器最后确认的版本，这并不证明每个会话都在显示它。升级失败或部分完成时还会带有 code、attempt、retry_at 和 missing_page_count。--human 会打印 Target v42 · Playing v41。失败的升级不会安排重试：先排除原因，然后运行 screen reload 或重新分配播放列表。已保存的分配不能确认播放。

当已配对的播放器无法显示 application 或 iframe 页面时会出现 applications_unsupported：清单不变，播放器会跳过这些页面。当丢失了已存储身份的显示器申请以此屏幕的身份重新连接时会出现 recovery_pending，其中包含该申请的 expires_at，以及显示器报告的 platform、model、firmware 和 manufacturer：参见 screen recover。

screen update#

一次调用即可修改屏幕的名称、播放列表分配、时区覆盖、字段或位置。

screen update <id> [--name NAME] [--playlist-id ID | --clear-playlist] [--timezone ZONE | --clear-timezone] [--field NAME=VALUE...] [--unset-field NAME...] [--clear-fields] [--location LAT,LON [--location-name NAME] [--address TEXT] | --clear-location] [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--name NAMEstring否未更改屏幕的显示名称。
--playlist-id IDstring否未更改此屏幕应运行的 pl_ 播放列表。不能与 --clear-playlist 同时使用。
--clear-playlistboolean否关闭清除屏幕自身的默认分配。配对和所有其他内容层级保持不变，若没有适用的内容，屏幕显示空闲状态。已归档的屏幕返回 screen_archived。不能与 --playlist-id 同时使用。
--timezone ZONEstring否未更改以 IANA 区域标识符覆盖屏幕的时区，如 America/Los_Angeles。根据服务器的区域数据库验证。不能与 --clear-timezone 同时使用。
--clear-timezoneboolean否关闭移除覆盖，使屏幕重新沿用其设备报告的时区。不能与 --timezone 同时使用。
--field NAME=VALUEstring否未更改设置一个字段，其他字段保持不变。可重复使用，每个名称只能出现一次。NAME 为 1 到 32 个小写字母、数字或下划线，VALUE 去除首尾空白后为 1 到 200 个字符，一个屏幕最多有 32 个字段。不能与 --clear-fields 同时使用。
--unset-field NAMEstring否未更改移除一个字段。可重复使用。不能与 --clear-fields 同时使用。
--clear-fieldsboolean否关闭移除所有字段。不能与 --field 或 --unset-field 同时使用。
--location LAT,LONstring否未更改屏幕所在的位置，以十进制度数表示：纬度 -90 到 90，经度 -180 到 180。会替换整个位置，所以要保留 --location-name 和 --address 就必须重复指定。不能与 --clear-location 同时使用。
--location-name NAMEstring否无卡片显示的简短地点名称，1 到 40 个字符。需要 --location。
--address TEXTstring否无供人员和智能体使用的地址，1 到 200 个字符。需要 --location。
--clear-locationboolean否关闭移除位置。不能与 --location 同时使用。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。

至少提供 --name、--playlist-id、--clear-playlist、--timezone、--clear-timezone、--field、--unset-field、--clear-fields、--location 或 --clear-location 中的一个。

screenrig screen update scr_01EXAMPLESCREEN00000000 --name "Lobby"
screenrig screen update scr_01EXAMPLESCREEN00000000 --field store_number=0142 --field region=north
screenrig screen update scr_01EXAMPLESCREEN00000000 --location 47.6062,-122.3321 --location-name "Seattle HQ"
screenrig screen update scr_01EXAMPLESCREEN00000000 --clear-playlist --expect-rev 3

审核中，仅--playlist-id的更改像screen assign一样被提议；提议会话无法更改其他字段。

更改字段或位置会改变屏幕的清单修订版本，因此显示播放列表的屏幕会获取新值。卡片和 iframe 页面按屏幕读取这些值，所以同一个播放列表可以显示各屏幕自己的值：{screen.field.NAME}、{screen.name} 和 {screen.timezone} 可填充卡片的任意文本参数，"location": "{screen.location}" 按该卡片所需的形式填充卡片的位置，卡片数据键可以包含 {screen.field.NAME}，例如 menu-{screen.field.store_number}。没有某个字段的屏幕会把该文本显示为空，卡片则不使用该数据键或位置。screen show 列出屏幕的字段和位置，screen list 则据此查找屏幕。参见iframe 地址和应用参数中的屏幕令牌。

screen publish#

从准备好的文件创建新播放列表并分配给屏幕。

screen publish <id> <file> [--expect-rev REVISION] [--note TEXT] [--no-wait] [--poll-ms MS] [--timeout MS] [--no-progress]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
<file>路径是无准备好的播放列表文档，或 - 表示标准输入。
--expect-rev REVISIONstring否无可选的 屏幕 修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
--no-waitboolean否关闭分配之后立即返回，不等待播放器显示播放列表。
--poll-ms MSinteger否2000等待期间轮询屏幕的间隔。
--timeout MSinteger否120000等待的截止时间。它也限制每个底层请求。
--no-progressboolean否关闭不在 stderr 上输出阶段信息。
screenrig screen publish scr_LOBBY lobby.json

这会创建一个新的播放列表并分配它。不会按名称更新现有播放列表。请先检查准备好的文档。重复相同输入以恢复模糊失败。分配回读不证明播放；请单独请求截图。审核中返回stage: pending_review，同时带有两个审核。详见准备、发布和编辑播放列表。

分配之后，命令会等待播放器显示该播放列表：data.stage 为 playing，data.playback_verified 为 true。阶段变化会随发生输出到 stderr，格式为 JSON 行，使用 --human 时为文本。发布完成后重复相同命令，只要屏幕仍在显示该播放列表，就会报告那次发布（data.already_published）；屏幕已切换到其他内容后，则会重新发布。

screen assign#

将一个屏幕或一组屏幕指向播放列表。

screen assign (<id>... | --tag TAG | --folder ID) --playlist-id ID [--expect-rev REVISION] [--note TEXT]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--playlist-id IDstring是无要运行的 pl_ 播放列表。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。省略则写入当前资源。提供的过时值为 revision_conflict：重新获取、重新应用、重试。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig screen assign scr_01EXAMPLESCREEN00000000 --playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen assign --tag Lobby --playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen assign --folder sfd_01EXAMPLEFOLDER000000000 --playlist-id pl_01EXAMPLEPLAYLIST000000

含有页面排程的播放列表可分配给任何屏幕：排程按该屏幕自己的时区读取（其覆盖值，否则为其设备报告的时区，否则为 UTC）。

要发布到设备群，先用 playlist create 创建播放列表，然后运行 screen assign --tag TAG --playlist-id ID。screen publish 针对单个屏幕。

在提议权限下，或项目要求对智能体的更改进行审核时，对单个屏幕或整个设备组的更改会改为返回 pending_review：data.review 带有审核 ID 及其仪表板 url，警告 pending_review 给出该 URL，data.next 为 reviews show ID。在有人批准之前，屏幕上不会有任何变化，因此不要重复写入。对于受保护文件夹中的屏幕，任何访问级别都返回 pending_review，由你以外、也不是你所代表的人的审批人决定（否则为 second_approver_required，退出码 3）。仅限屏幕文件夹的调用方只能对其范围内的屏幕进行分配。已保存的分配不能确认播放；screen screenshot 可查看屏幕上的实际画面。

screen set-timezone#

覆盖屏幕按其读取本地时间规则的时区，或移除该覆盖。

screen set-timezone <id> (--timezone ZONE | --clear) [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--timezone ZONEstring--timezone 或 --clear 之一无以 IANA 区域标识符覆盖屏幕的时区，如 Europe/Berlin。
--clearboolean--timezone 或 --clear 之一关闭移除覆盖，使屏幕重新沿用其设备报告的时区。不能与 --timezone 同时使用。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen set-timezone scr_01EXAMPLESCREEN00000000 --timezone America/Los_Angeles
screenrig screen set-timezone scr_01EXAMPLESCREEN00000000 --clear

每个屏幕都有一个生效时区，所有本地时间规则都按它读取：页面可见性、广告位、播放列表计划、接管、活动、显示器和重启计划，以及 {screen.timezone}。它是此覆盖值，否则是屏幕的播放器从其设备报告的时区，否则是 UTC。只要设备报告的时区正确，屏幕就不需要覆盖值。screen show 以 Timezone 打印生效时区及其来源，effective_timezone 和 timezone_source（screen、device 或 default）位于 --json 中。更改生效时区会重新生成清单修订号。

ZONE 为 Area/City，例如 America/New_York 或 Asia/Tokyo，或 UTC。

screen wall set#

设置屏幕的视频墙：由一个播放器把两到十二台显示器作为一块画布来驱动。

screen wall set <id> --outputs NAMES --arrangement row|column|grid [--columns N] [--rotation 0|90|180|270] [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--outputs NAMESstring是无按物理顺序（先从左到右、再从上到下）排列的二到十二个以逗号分隔的输出名称，即 screen show 在 observation.surfaces 下列出的名称，例如 HDMI-A-1,HDMI-A-2。每个名称为 1 到 64 个字母、数字、点、下划线或连字符，且不可重复。
--arrangement ARRANGEMENTstring是无row（单行，从左到右）、column（单列，从上到下）或 grid（每行 --columns 个输出，从上到下）。
--columns Ninteger是，针对 grid无网格每行的输出数：2 到 6，且须能把输出分成至少 2 行。用于 row 和 column 时会被拒绝。
--rotation DEGREESstring否0所有输出的顺时针旋转角度：0、90、180 或 270。90 和 270 为竖屏面板。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen wall set scr_01EXAMPLESCREEN00000000 --outputs HDMI-A-1,HDMI-A-2 --arrangement row
screenrig screen wall set scr_01EXAMPLESCREEN00000000 --outputs DP-1,DP-2,DP-3 --arrangement row --rotation 90 --expect-rev 4
screenrig screen wall set scr_01EXAMPLESCREEN00000000 --outputs DP-1,DP-2,DP-3,DP-4,DP-5,DP-6 --arrangement grid --columns 3

一个播放器将这些显示器作为一面墙驱动，因此播放列表页面会横跨所有显示器。设置会替换整个视频墙，所以要保留 --rotation 和 --columns 就必须重复指定。只有 Linux 播放器的 kiosk 安装和 Windows 播放器声明 display.wall 能力；其他任何播放器都返回 wall_unsupported（退出码 5），且不会有任何更改。提议权限不能更改视频墙（insufficient_access）。2 或 3 台显示器的视频墙需要 Plus 或更高套餐，4 到 12 台显示器的需要 Enterprise：不含该功能的套餐会返回 feature_not_in_plan（退出码 8），而 screen wall clear 和保留已存储视频墙的设置仍可进行。参见视频墙。

用 playlist init 加上屏幕的 ID，按视频墙的形状编写播放列表，它会写入匹配的画布和 format（displays、arrangement、orientation，网格还有 columns）。图元的 displays（如 [2] 或 [1, 2, 5, 6]）指明它覆盖的显示器编号，编号从 1 开始，先从左到右、再从上到下，并且必须填满视频墙的一个矩形。分配格式与视频墙形状不符的播放列表会返回 playlist_format_mismatch（退出码 5）；没有格式的播放列表在每个显示器上播放相同的内容。屏幕播放格式匹配的播放列表后，每次更改后 20 秒内，每个显示器都会显示自己的编号和名称，方便你在屏幕上核对顺序。

screen wall clear#

移除屏幕的视频墙。

screen wall clear <id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen wall clear scr_01EXAMPLESCREEN00000000

已分配的播放列表不会被重新检查：如果它带有 format，屏幕的清单会降级（wall_format_mismatch），播放器会保留最后一个正常页面，直到你分配一个没有格式的播放列表。没有视频墙的屏幕则原样响应。提议权限不能更改视频墙（insufficient_access）。

screen archive#

隐藏屏幕并使其玻璃变暗。

screen archive <id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen archive scr_01EXAMPLESCREEN00000000

归档会将屏幕从默认列表中隐藏，并使玻璃变暗。它不会解除播放器的绑定。

持有显示器密钥的人，在屏幕归档期间仍可连接。要彻底停用硬件，请让屏幕保持归档，或用 screen recover 或 screen replace 把屏幕迁移到新硬件，二者都会使旧密钥失效。

screen unarchive#

恢复归档的屏幕至默认列表。

screen unarchive <id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen unarchive scr_01EXAMPLESCREEN00000000

一个播放器也可以归档自己的屏幕：持有密钥的播放器确认重置，或通过 Cookie 配对的浏览器播放器取消配对。screen show 然后报告 archive_reason 为 device_reset 或 device_unpair（project 为你请求的归档），带 archived_at。屏幕保留其设备绑定，持有该密钥或设备 Cookie 的播放器保持暗屏，取消归档时恢复，无需重新配对。被重置或取消配对的播放器丢弃密钥或 Cookie，作为新屏幕重新配对。确认屏幕恢复替换的密钥保持废弃。

由 screen replace 归档为 replaced 的屏幕不保留设备绑定，因此取消归档会拒绝它，screen delete 则会将其删除。

screen suspend#

在屏幕上显示通知以代替其内容，直到屏幕恢复。

screen suspend <id> --message TEXT [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--message TEXTstring是无屏幕显示的通知：修剪后为 1 到 280 个字符。换行符是唯一允许的控制字符，播放器会自动换行并保留其中的换行符。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen suspend scr_01EXAMPLESCREEN00000000 --message "Closed for stocktake. Back at 9am."

已暂停的屏幕显示该消息以代替其内容。其他一切不变：其播放列表、排程、接管和显示控制仍然保留并继续演进，而 screen resume 会让屏幕显示其此刻本应显示的内容。screen show 报告 suspension，带有 message 和 since；对已暂停的屏幕再次暂停会替换消息并保留 since。暂停会提升屏幕版本，播放器立即重新获取。归档屏幕返回 screen_archived。

screen resume#

结束屏幕的暂停，使其重新显示自身内容。

screen resume <id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen resume scr_01EXAMPLESCREEN00000000

恢复会让屏幕重新显示自身内容，以屏幕此刻本应显示的内容为准，播放器会立即重新获取。未暂停的屏幕原样返回，版本不变。归档屏幕返回 screen_archived。

screen delete#

删除屏幕。

screen delete <id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen delete scr_01EXAMPLESCREEN00000000

只有在没有播放器密钥绑定到屏幕时才能删除它，此时 screen show 为该屏幕报告 deletable: true。通过代码配对的播放器，无论是本地播放器还是浏览器播放器，都持有密钥，该密钥保持绑定在其屏幕上，因此删除这样的屏幕会返回 409 screen_archive_required（退出码 5）：请改为归档。只有通过 Cookie 配对的浏览器播放器不持有密钥，其屏幕无论已配对还是仍在等待，都可以删除。

要把持有密钥的显示器配对为新屏幕，请在播放器上确认重置，然后用 screen pair 认领它显示的配对码；旧屏幕保持归档状态。要把屏幕迁移到替换用硬件，请使用 screen recover；如果该硬件已作为独立屏幕配对，则使用 screen replace。

screen recover#

把丢失了已存储身份的显示器重新连接到它原先配对的屏幕。

screen recover <id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen show scr_01EXAMPLESCREEN00000000
screenrig screen recover scr_01EXAMPLESCREEN00000000

丢失了已存储身份的显示器在配对期间报告此屏幕的硬件标识符时，会提出申请。screen show 将其报告为 recovery_pending，并附带截止时间；显示器如有报告，还包括其 platform、model、firmware 和 manufacturer。在此命令确认之前不会重新绑定任何内容：屏幕保留其标签、播放列表、时区、计划和历史记录，显示器的新密钥取代原密钥，原密钥在十五分钟宽限期后失效。因设备重置而归档的屏幕会一直保持归档，直到执行 screen unarchive。

确认之前，请将报告的型号和固件与你预期的显示器核对：显示器上运行的任何应用都可以读取其标识符，所以仅凭申请本身并不能证明是哪台显示器提出的。当屏幕当前的播放器仍在线时，服务会拒绝申请，且每个屏幕每小时最多接受三次申请。没有申请时，命令返回 recovery_not_offered；配对会话已失效的申请返回 recovery_expired；标识符关联到多个屏幕时返回 recovery_ambiguous；以上情况都不会重新绑定任何内容。恢复绝不会跨项目进行。

screen replace#

将配对为另一个屏幕的设备移到此屏幕，保留此屏幕的设置和历史记录。

screen replace <id> --with ID [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无要保留的 scr_ 屏幕。
--with IDstring是无scr_ 屏幕，其配对设备将接手本屏幕。必须是项目中的另一个屏幕。
--expect-rev REVISIONstring否无针对要保留屏幕的可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen replace scr_01EXAMPLESCREEN00000000 --with scr_01EXAMPLENEWSCREEN000000

先将新硬件配对为独立的屏幕，再替换。设备的密钥或浏览器播放器的凭据现在打开的是 <id>，该屏幕保留其名称、标签、时区、播放列表、排程、接管、显示排程和覆盖、视频墙、评论、字段、位置和历史记录，并采用替换方的主机和播放器。其健康、状态、存储和排队命令重新开始。由 --with 指定的屏幕被归档，archive_reason 为 replaced，replaced_by 指明 <id>。它不保留设备绑定，因此 screen unarchive 无法恢复它，screen delete 会将其删除。<id> 原先持有的密钥在十五分钟宽限期后废弃，此后其旧设备将被拒绝。两个屏幕都必须处于活动状态并带有已配对的播放器：仍在等待配对的屏幕返回 resource_conflict，已归档的屏幕返回 screen_archived，视频墙则需要声明 display.wall（wall_unsupported）的替换播放器。请求始终携带幂等键，完全相同的重试会返回原始响应。

要移动已丢失存储身份、并报告此屏幕标识符的显示器，请使用 screen recover。

screen rotate-public-id#

为屏幕发放新的公共 ID。

screen rotate-public-id <id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen rotate-public-id scr_01EXAMPLESCREEN00000000

屏幕的 public_id（其公开 URL 中的凭据）会被替换，用旧凭据打开的所有会话都会结束。播放器的配对保持不变：已配对的播放器会打开新会话，并继续显示其内容。

screen reload#

请求屏幕的播放器，或舰队中的所有播放器，重新加载一次。

screen reload (<id>... | --tag TAG | --folder ID) [--expires-in DURATION] [--expect-rev REVISION]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--expires-in DURATIONstring否24h，由服务器应用请求等待离线屏幕上线的时间：90s、30m、2h 或 1d，范围从 60s 到 24h。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。
screenrig screen reload scr_01EXAMPLESCREEN00000000
screenrig screen reload scr_01EXAMPLESCREEN00000000 --expires-in 2h
screenrig screen reload --tag Lobby
screenrig screen reload --folder sfd_01EXAMPLEFOLDER000000000

响应携带 reload_id、state 和 expires_at。在线屏幕会立即收到重载（state 为 sent）；离线屏幕将其置于 queued 状态，若该屏幕在 expires_at（请求后 24 小时，除非 --expires-in 另行指定）之前上线，便会收到它。较新的重载会取代仍在排队的重载，screen show 列出屏幕的 commands，screen command cancel 取消仍在排队的重载。车队中，每个结果的 reload 携带相同的 state。网页播放器在下一页面边界重新加载；原生播放器重新连接，重新获取清单并检查更新。播放器忽略十分钟内的重复重载。重载适用于活动和归档屏幕，不更改屏幕版本。

screen toast#

在实时屏幕或屏幕组上发布一个临时舞台界面消息。

screen toast (<id>... | --tag TAG | --folder ID) --text TEXT [--level info|alert|error] [--duration-ms MS]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--text TEXTstring是无一到 120 个字符，换行符为唯一换行，最多三行。
--level LEVELstring否infoinfo、alert 或 error。屏幕可以设置其显示的最低提示级别，error 提示始终显示。播放器将提示显示在一行内，换行显示为空格。命令成功并不代表提示可见。
--duration-ms MSinteger否60000，由服务器应用提供时介于2000和60000之间。
screenrig screen toast scr_01EXAMPLESCREEN00000000 --text "Lobby closed"
screenrig screen toast --tag Lobby --text "Closing in ten minutes"
screenrig screen toast --folder sfd_01EXAMPLEFOLDER000000000 --text "Closing in ten minutes"

Toast 不是原语：不占画布槽，无图层，不参与就绪或交叉淡入。最新覆盖，无队列无取消，接受的信封仅 { expires_at }。文本中绝不放凭证或其他秘密材料。

screen identify#

在屏幕内容上方显示其名称一段时间，以便在现场找到它。

screen identify <id> [--duration DURATION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--duration DURATIONstring否60s，由服务器应用覆盖层保持显示的时间，从播放器收到请求时算起：30s、2m 或 1m30s，范围从 2s 到 10m。
screenrig screen identify scr_01EXAMPLESCREEN00000000
screenrig screen identify scr_01EXAMPLESCREEN00000000 --duration 2m

播放器在其内容之上绘制全屏覆盖层，屏幕名称非常大，其 ID 以小字显示在名称下方。播放在覆盖层下方继续，较新的标识请求会替换该覆盖层。接受的信封携带 identify_id、duration_ms 和请求后 60 秒的 expires_at，因此离线屏幕此后绝不会显示它。只有声明 identify 能力的播放器才会显示该覆盖层：其他任何屏幕返回 409 identify_unsupported（退出码 5）且不发送任何内容，因此请更新播放器，或使用 screen toast 显示名称。归档屏幕返回 screen_archived，仍在等待配对的屏幕返回 resource_conflict。标识屏幕不会更改屏幕版本。

screen play-page#

启动屏幕当前正在播放的播放列表中的某个页面，以便用截图检查该页面。

screen play-page <id> --page-id ID
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--page-id IDstring是无屏幕当前正在播放的播放列表中的某个页面：1 到 128 个字符。
screenrig screen play-page scr_01EXAMPLESCREEN00000000 --page-id welcome
screenrig screen screenshot scr_01EXAMPLESCREEN00000000

页面会在播放器上从头开始，轮播从那里继续，因此接着截取的截图无需等待轮播，就能显示该页面。该页面必须属于屏幕当前播放的播放列表：它的接管，否则是生效的活动，否则是其计划，否则是其已分配的播放列表。其他任何页面都会返回 page_not_on_screen（退出码 5），问题详情会指明那个播放列表。未在主机报告中声明 play_page 能力的播放器返回 play_page_unsupported（退出码 5），且不发送任何内容：请更新播放器。

响应包含 playlist_id、page_id、manifest_revision 和 expires_at。请求在 60 秒后失效，不会更改屏幕的修订版本。已归档的屏幕返回 screen_archived，仍在等待配对的屏幕返回 resource_conflict。使用相同幂等键重试会重放原来的响应。

screen screenshot#

捕获一个活动屏幕的静态图像，或捕获舰队中每个屏幕的静态图像，并写入磁盘。

screen screenshot <id> [--output FILE] [--timeout MS] [--poll-ms MS]
screen screenshot (<id> <id>... | --tag TAG | --folder ID) [--output DIRECTORY] [--concurrency N] [--timeout MS] [--poll-ms MS]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕，无屏幕数量限制。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕，不限屏幕数量。
--output FILE路径否./<id>.webp针对单个屏幕，提供文件路径；已有文件将被覆盖且无提示。针对多个 ID、--tag 或 --folder，提供目录，若不存在则创建，每个屏幕生成一个 <screen_id>.webp。
--concurrency Ninteger否4同时捕获多个 ID、--tag 或 --folder，数量从 1 到 8。
--timeout MSinteger否35000等待截图的时间。
--poll-ms MSinteger否500捕获状态轮询间隔。
screenrig screen screenshot scr_01EXAMPLESCREEN00000000 --output ./lobby.webp
screenrig screen screenshot --tag Lobby --output ./lobby-shots
screenrig screen screenshot --folder sfd_01EXAMPLEFOLDER000000000 --output ./north-shots

命令会阻塞，直到 WebP 写入磁盘。封装包含 screen_id、capture_id、path、bytes、sha256、width 和 height，从不包含图像字节。以最新请求为准：后来的请求会取代正在进行的截图。播放器 Web 应用的截图会把每个 iframe 页面绘制为标有“Embedded web page”的深灰色方块，把每个应用绘制为应用自身渲染的内容；图像中没有该方块的标记，因此不能证明 iframe 页面已渲染。

给出多个 ID、--tag 或 --folder 时，结果是一个设备群结果，包含 action: "screenshot"、selector 和 output 目录；每个 ok 结果带有 path、bytes、sha256、width 和 height。使用 --tag 时，CLI 先列出带标签的屏幕，并跟进每个列表页；每个列表页是一个智能体请求，截图本身不计数，多个 ID 则不需要列表。这种形式下 --idempotency-key 会被拒绝，因为每次截图使用各自的密钥。如果某次截图意外失败，该屏幕的结果为 unexpected_error，不再开始新的截图，仍在等待的屏幕报告 not_attempted，退出码为 1。

对单个屏幕，封装中还包含 frame.flat（这张图像是否为单一纯色）和 picture（屏幕的空白或静止判定，有则显示）。仅凭一张纯色图像不能下结论：页面之间的过渡，或刻意设为黑色的页面，看起来也是如此。使用 --folder 时，CLI 会列出该文件夹及其内部的每个文件夹，每个文件夹执行一次 screen list --folder，列表中显示为离线的屏幕不进行截图，直接报告为失败。

服务器每分钟允许每个屏幕 10 次、每个组织 30 次、每个地址 30 次截图；CLI 会用退避方式重试 429 和 5xx 响应，并遵守 Retry-After。无法完成的截图会返回 screenshot_unavailable（退出码 5）：屏幕离线、请求 timed_out、所显示的页面包含播放器无法捕获的内容（unsupported_surface，例如浏览器播放器中可见的第三方 iframe）、播放器的捕获失败（capture_failed），或 --timeout 到期时截图仍在等待。--timeout 0 会把等待交给服务器，服务器会在 30 秒后让无响应的请求失效。当播放器已报告其显示器状态时，失败的截图会带有 error.display：power、connected、reported_at 和 stale（35 分钟后）。若最新报告是 off 或 standby，建议在显示器开启时重试。

screen live start#

启动屏幕的实时视图或为其续期，并输出显示它的仪表板页面。

screen live start <id> [--duration DURATION] [--wait DURATION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--duration DURATIONstring否5m会话在不续期时持续的时间：30s 到 5m，例如 90s 或 5m。会话最迟在开始五分钟后结束。
--wait DURATIONstring否30s等待播放器开始发布的时间：1s 到 10m，或用 0 立即返回。
screenrig screen live start scr_01EXAMPLESCREEN00000000
screenrig screen live start scr_01EXAMPLESCREEN00000000 --duration 2m --wait 60s

实时视图在仪表板中以视频形式显示屏幕正在播放的内容；CLI 只负责启动、读取和停止会话，从不传输视频。data 是会话，其中包含要打开的页面 viewer_url。对已有会话的屏幕再次启动会续期：租约变为当前结束时间与从现在起 --duration 之后的时间中较晚者，但不会超过会话开始后的五分钟。之后会话自行结束：不会续期或重启，下一个会话需要新的 screen live start。租约到期、执行 screen live stop，或播放器结束会话时，会更早结束。

命令请求播放器发布，并在 --wait 内每秒读取一次会话，直到播放器报告已连接。如果等待结束时播放器仍未连接，响应仍然是 ok，并带有警告 live_not_ready：再次读取 screen live status，或打开 viewer_url。等待期间结束的会话为 live_unavailable（退出码 5），其详情会给出 ended_reason，例如 consent_timeout（在 Android 上，每次播放器启动时，都需要屏幕前的人允许屏幕捕获）。离线的屏幕同样是 live_unavailable，已归档的屏幕返回 screen_archived。未声明 live_view 能力的播放器返回 live_unsupported（退出码 5），且不发送任何内容：请更新播放器。没有媒体中继的服务器返回 feature_unavailable：请改用 screen screenshot。实时视图免费。参见实时视图。

screen live status#

读取屏幕的实时视图会话。

screen live status <id>
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
screenrig screen live status scr_01EXAMPLESCREEN00000000

state 为 idle（无会话）、requested（已请求播放器）、publishing（中继持有其视频）或 ended，ended_reason 会保留十分钟。publisher.connected 是播放器自己的报告，最多为 45 秒前的数据，不能证明有画面。data 包含 viewer_url。

screen live stop#

结束屏幕的实时视图会话。

screen live stop <id>
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
screenrig screen live stop scr_01EXAMPLESCREEN00000000

结束会话并通知播放器停止发布，然后输出当前的会话：ended，其 ended_reason 为 stopped。没有会话时也会成功。租约到期时，会话也会自行结束。

screen live frame#

从实时流中保存屏幕所播放内容的 JPEG 帧，用于检查播放和画面运动。

screen live frame <id> [--output PATH] [--count N] [--interval DURATION] [--duration DURATION] [--wait DURATION] [--stop]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--output PATH路径否工作目录单帧时为文件，否则为接收每帧 frame-<captured_at>.jpg 的目录，时间中的冒号写作连字符。--count 大于 1 时需要目录。
--count Ninteger否1要保存的新帧数量。
--interval DURATIONstring否1s帧与帧之间的间隔：1s 到 5m，或用 0 在每帧到达时立即获取。
--duration DURATIONstring否2m此命令启动的实时会话的租约：30s 到 5m。它会延长到足以覆盖这些帧再加 30 秒，需要超过五分钟的运行会被拒绝。
--wait DURATIONstring否30s等待播放器开始发布以及等待每一帧的时间：1s 到 10m，或用 0 只尝试一次。
--stopboolean否关闭完成后结束实时会话，帧获取失败时也会结束。
screenrig screen live frame scr_01EXAMPLESCREEN00000000
screenrig screen live frame scr_01EXAMPLESCREEN00000000 --output now.jpg --stop
screenrig screen live frame scr_01EXAMPLESCREEN00000000 --output frames/ --count 5 --interval 1s

命令会启动实时会话，等待播放器发布，向媒体中继请求帧，并把每个新帧读取一次。一帧就是播放器编码器发送的视频，缩放到最大 1280x720 且有损，约每秒一帧：它能显示画面运动和屏幕上当前的内容，所以可比较多帧（--count 5 --interval 1s）来检查内容是否在动。它不是截图，版面检查仍以截图为准。帧免费。

data 为 {screen_id, live_id, frames}，每帧包含 path、captured_at、width、height、bytes 和 sha256；当 --stop 结束会话时，stopped 为 true。没有 --stop 时，会话交由其租约处理。播放器在 --wait 内未开始发布，或在此时间内没有发送新帧，则为 live_not_ready（退出码 5）；在 Android 上，每次播放器启动时，都需要屏幕前的人允许屏幕捕获。已结束的会话，或帧不再到达的会话，为 live_unavailable（退出码 5）。没有 live_view 能力的播放器返回 live_unsupported，没有媒体中继或帧功能的服务器返回 feature_unavailable（退出码 4）：请改用 screen screenshot。

screen tag#

设置、添加、移除或清除屏幕或设备组的标签。

screen tag (<id>... | --tag TAG | --folder ID) (--set TAGS | --add TAGS | --remove TAGS | --clear) [--expect-rev REVISION]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--set TAGSstring恰好一个操作无用这些逗号分隔的标签替换整个集合，例如Lobby,Floor2。
--add TAGSstring恰好一个操作无添加这些逗号分隔的标签。
--remove TAGSstring恰好一个操作无移除这些逗号分隔的标签。
--clearboolean恰好一个操作关闭移除所有标签。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。
screenrig screen tag scr_01EXAMPLESCREEN00000000 --set Lobby,Floor2
screenrig screen tag scr_01EXAMPLESCREEN00000000 --add Spring
screenrig screen tag --tag Lobby --add Spring
screenrig screen tag --folder sfd_01EXAMPLEFOLDER000000000 --add Spring

标签为 1 到 32 个字母或数字，屏幕最多携带 16 个唯一标签。标签选择舰队；绝非授权，且永不传达给播放器。更改标签提升屏幕版本，不提升清单版本。单屏时信封为更新的屏幕。--add 和 --remove 先读取屏幕，再用 --expect-rev 或刚读的版本写入新集合，避免并发改写，返回 revision_conflict（退出码 6）；重试命令。舰队中，--add 和 --remove 原子应用于每屏幕存储集合，超出 16 标签的屏幕在自身结果中失败，返回 invalid_request。

凡标签发生变化之处（screen tag、通过 API 更新屏幕、控制台标签编辑器），响应中的 levels 在 gained 和 lost 下列出屏幕加入或离开其标签受众的活动，每项带有其 source (campaign)、id、screens 数量，以及活动具有 reach 时的 reach_before 和 reach_after。车队 screen tag 会在整个车队上对它们求和。在断定标签编辑无害之前，请先读取 levels.lost：从活动的屏幕上移除最后一个匹配的标签会使该分组为空，并触发 reach_dropped 和 group_empty 通知。

screen move#

把屏幕和屏幕文件夹移入某个屏幕文件夹，或移回项目根目录。

screen move <id>... (--folder ID | --root) [--note TEXT]
参数类型必填默认备注
<id>...string是无scr_ 屏幕 ID 和 sfd_ 屏幕文件夹 ID，可任意混合，每个只能出现一次，合计最多 1000 个。
--folder IDstring--folder 或 --root 之一无目标 sfd_ 屏幕文件夹。
--rootboolean--folder 或 --root 之一关闭移到项目根目录，即不属于任何文件夹。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig screen move scr_01EXAMPLESCREEN00000000 --folder sfd_01EXAMPLEFOLDER000000000
screenrig screen move sfd_01EXAMPLEFOLDER000000000 --root

移动是一次全有或全无的请求。文件夹连同其中所有内容一起移动，不能移入其自身或其内部的文件夹；文件夹最多嵌套 10 层。已在目标位置的项目保持原样，也不计入。data.screens 和 data.folders 统计已移动的数量。data.levels 在 gained 和 lost 下列出被移动的屏幕进入或离开其文件夹受众的活动（source campaign，带有 reach_before 和 reach_after），以及它们开始或不再显示的文件夹默认播放列表（source folder）。这些屏幕会在大约 15 秒内重新解析其播放列表；screen show 会报告 effective_playlist，campaign explain SCREEN_ID 则说明原因。

仅限屏幕文件夹的调用方只能把其范围内的屏幕和文件夹移入其范围内的文件夹；其他任何目标，包括项目根目录，都会使整个移动请求被 outside_screen_scope（退出码 3）拒绝。移入或移出受保护文件夹会返回 pending_review 并生成 protected_change 审核，由第二位审批人决定，因此不要重复写入；--note 可向审批人说明原因。请求中断后，重新运行相同命令即可复用已保存的幂等键。

screen folder list#

以树形列出项目的屏幕文件夹，并显示直接位于每个文件夹中的活动屏幕及其默认播放列表。

screen folder list
screenrig screen folder list

返回项目的所有屏幕文件夹，最多 1000 个，按名称排序。data.items 包含每个文件夹的 id、name、parent_id（位于项目根目录时 null）、已设置时的 default_playlist_id 和 protected、screens（直接位于其中的活动屏幕，不含下级文件夹中的）以及 revision。使用 --human 时，输出为树形，每个文件夹一行并显示其路径。屏幕的文件夹是 screen list 和 screen show 上的 folder_id，位于项目根目录时不存在。只读权限即可。

screen folder show#

查看屏幕文件夹。

screen folder show <id>
参数类型必填默认备注
<id>string是无sfd_ 屏幕文件夹 ID。
screenrig screen folder show sfd_01EXAMPLEFOLDER000000000

返回一个文件夹，字段与 screen folder list 返回的相同。只读权限即可。

screen folder create#

在项目根目录或另一个文件夹内创建屏幕文件夹。

screen folder create --name NAME [--parent ID] [--default-playlist-id ID] [--note TEXT]
参数类型必填默认备注
--name NAMEstring是无文件夹名称，已去除首尾空白：1 到 100 个字符，不含控制字符，不能是 . 或 ..，且在同级文件夹中唯一（resource_conflict，退出码 5）。
--parent IDstring否项目根目录在此 sfd_ 屏幕文件夹内创建。
--default-playlist-id IDstring否无屏幕自身没有播放列表时所显示的已批准 pl_ 播放列表（未批准则返回 playlist_not_approved，退出码 5）。离该屏幕更近的文件夹若另有设置，则以那个为准。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig screen folder create --name "North Tower"
screenrig screen folder create --name "Level 2" --parent sfd_01EXAMPLEFOLDER000000000 --default-playlist-id pl_01EXAMPLEPLAYLIST000000

一个组织跨其所有项目最多持有 1000 个文件夹（quota_exceeded），嵌套最多 10 层（invalid_request）。用 screen move 把屏幕放入文件夹。之后文件夹可在设备组命令中和作为活动受众来指定其中的屏幕：参见屏幕文件夹。

仅限屏幕文件夹的调用方只能在其范围内创建文件夹：--parent 必须是其范围内的文件夹（outside_screen_scope，退出码 3）。在受保护文件夹中创建的文件夹返回 pending_review，并生成 protected_change 审核，需由你以外、也不是你所代表的人的审批人来决定，因此不要重复写入；--note 可向审批人说明原因。请求中断后，重新运行相同命令即可复用已保存的幂等键。

screen folder update#

重命名屏幕文件夹、连同其中内容一起移动，或设置、清除其默认播放列表。

screen folder update <id> [--name NAME] [--parent ID | --root] [--default-playlist-id ID | --clear-default] [--expect-rev REVISION] [--note TEXT]
screen folder update <id> --unprotect [--expect-rev REVISION] [--note TEXT]
参数类型必填默认备注
<id>string是无sfd_ 屏幕文件夹 ID。
--name NAMEstring否未更改新的文件夹名称，规则与 screen folder create 相同。
--parent IDstring否未更改连同其中所有内容，移到此 sfd_ 屏幕文件夹下。不能与 --root 同时使用。
--rootboolean否关闭移到项目根目录。不能与 --parent 同时使用。
--default-playlist-id IDstring否未更改屏幕自身没有播放列表时所显示的已批准 pl_ 播放列表。不能与 --clear-default 同时使用。
--clear-defaultboolean否关闭移除其默认播放列表。不能与 --default-playlist-id 同时使用。
--unprotectboolean否关闭提议解除文件夹的保护。它单独发送，不能带上面的任何选项，由第二位审批人决定该审核。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。

至少提供 --name、--parent、--root、--default-playlist-id、--clear-default 或 --unprotect 中的一个。

screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --name "Northern"
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --root
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --default-playlist-id pl_01EXAMPLEPLAYLIST000000 --expect-rev 3
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --clear-default
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --unprotect --note "Menu boards move next week"

文件夹不能移入其自身或其内部的文件夹，设置相同的值则不会产生任何更改。移动或更改默认值会在大约 15 秒内重新解析其中的屏幕，data.levels 会列出这些屏幕进入或离开其文件夹受众的活动（source campaign），以及它们获得或失去的文件夹默认播放列表（source folder）。

重命名在受保护文件夹上立即生效。移动受保护文件夹或包含受保护文件夹的文件夹，或更改其默认播放列表，会返回 pending_review 并生成 protected_change 审核，由第二位审批人决定（即你以外、也不是你所代表的人的审批人；否则为 second_approver_required，退出码 3）。在此之前不会有任何更改，因此不要重复写入；--note 可向审批人说明原因。有审批权限的人在仪表板中保护文件夹；CLI 只能通过 --unprotect 提议解除保护。参见受保护文件夹。仅限屏幕文件夹的调用方只能更改其范围内的文件夹，且只能把它们移到其范围内的父文件夹下（outside_screen_scope，退出码 3），也不能更改其范围所指定文件夹的保护状态。

screen folder delete#

删除屏幕文件夹；其中的屏幕和文件夹上移一级。

screen folder delete <id> [--expect-rev REVISION] [--note TEXT]
参数类型必填默认备注
<id>string是无sfd_ 屏幕文件夹 ID。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig screen folder delete sfd_01EXAMPLEFOLDER000000000
screenrig screen folder delete sfd_01EXAMPLEFOLDER000000000 --expect-rev 3

只删除文件夹本身：其中的屏幕和文件夹上移到其父文件夹（没有父文件夹时为项目根目录），这些屏幕会重新解析其播放列表。data 为 id、deleted true 和 levels（被移动的屏幕获得或失去的活动和文件夹默认播放列表，活动还带有 reach_before 和 reach_after）。如果有活动受众指定了该文件夹，删除会以 resource_conflict（退出码 5）被拒绝：请先更改或删除这些活动。

仅限屏幕文件夹的调用方只能删除其范围内的文件夹，不能删除其范围所指定的文件夹（outside_screen_scope，退出码 3）。受保护的文件夹，或包含受保护文件夹的文件夹，返回 pending_review 并生成 protected_change 审核，由第二位审批人决定，因此不要重复写入；--note 可向审批人说明原因。

设备组结果

给出多个屏幕 ID 或 --tag 时，screen assign、screen reload、screen toast 和 screen tag 执行一次不限屏幕数的操作。CLI 会自动跟进有限的结果页，在控制预算用尽时等待，并始终保持相同的密钥和所选设备群。--tag 只选择活动屏幕；ID 可以指向任何屏幕。只给一个屏幕 ID 时保持单屏幕结果。设备群命令不接受 --expect-rev，因为修订保护是按屏幕设置的。每条设备群命令都带有幂等性密钥。请求中断后（例如连接丢失），重新运行相同命令即可重放已完成的屏幕，而不会重复其副作用。在得到带有失败的明确结果后，只重试失败的 ID：重新运行整条命令会再次作用于每块屏幕。在 24 小时内重用相同的显式 --idempotency-key 会返回已记录的结果。

设备组命令接受屏幕 ID、--tag TAG 或 --folder ID；同时给出多个属于用法错误（退出码 2）。

信封保留 ok: true。部分成功是正常答案，不是传输错误：

{
  "ok": true,
  "data": {
    "action": "reload",
    "matched": 3, "succeeded": 2, "failed": 1,
    "results": [
      { "screen_id": "scr_LOBBY", "status": "ok", "reload": { "reload_id": "…", "expires_at": "…", "state": "sent" } },
      { "screen_id": "scr_GONE", "status": "failed", "problem": { "code": "not_found", "status": 404 } },
      { "screen_id": "scr_ENTRANCE", "status": "ok", "reload": { "reload_id": "…", "expires_at": "…", "state": "queued" } }
    ]
  },
  "warnings": [{ "code": "fleet_partial_failure", "message": "1 of 3 screens failed; 2 succeeded." }]
}

一个 ok 结果包含单屏结果：revision 用于 assign，revision 和 tags 用于标签更改，reload 用于重新加载，toast 用于吐司。一个 failed 结果包含该屏幕自身请求本应返回的问题。舰队操作内仍适用每屏限制，因此舰队重新加载或吐司可能报告刚刚重新加载或吐司的屏幕为 rate_limited；稍后重试该屏幕 ID。每屏限制为每分钟 6 次重新加载和 20 次吐司。舰队重新加载和吐司还使用组织预算，每分钟 600 屏幕：预算耗尽时服务器暂停，CLI 在继续自动操作前遵守 Retry-After。

结果退出代码警告
每个匹配的屏幕都成功了0无
部分或全部屏幕失败第一个失败屏幕的代码，如 4 对应 not_found 或 6 对应 revision_conflictfleet_partial_failure
无匹配屏幕0fleet_no_match
选择器或操作格式错误2 或请求自身代码；无屏幕变更无

屏幕文件夹

屏幕文件夹按地点组织屏幕。文件夹 ID 以 sfd_ 开头，一个屏幕最多位于一个文件夹中，在 screen show 和 screen list 中以 folder_id 报告，位于项目根目录时不存在。组织跨其所有项目最多持有 1000 个文件夹，嵌套深度最多 10 级，名称为 1 到 100 个字符，且在同级文件夹中唯一。标签仍用于跨越地点的分组。

screen folder list
screen folder show <id>
screen folder create --name NAME [--parent ID] [--default-playlist-id ID] [--note TEXT]
screen folder update <id> [--name NAME] [--parent ID | --root] [--default-playlist-id ID | --clear-default] [--unprotect] [--expect-rev REVISION] [--note TEXT]
screen folder delete <id> [--expect-rev REVISION] [--note TEXT]
screen move <id>... (--folder ID | --root) [--note TEXT]
screenrig screen folder create --name "North Tower"
screenrig screen folder create --name "Level 2" --parent sfd_01EXAMPLEFOLDER000000000 --default-playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen move scr_01EXAMPLESCREEN00000000 --folder sfd_01EXAMPLEFOLDER000000000

screen folder list 在 data.items 中返回每个文件夹，包含 id、name、parent_id（项目根目录为 null）、已设置时的 default_playlist_id、screens（直接位于其中的活动屏幕）和 revision。screen move 接受任意混合的屏幕 ID 和文件夹 ID，一次全有或全无的请求中最多 1000 个；文件夹连同其中所有内容一起移动，不能移动到自身或其内部的文件夹中。screen list --folder ID 仅列出直接位于某个文件夹中的屏幕。

在每个接受 --tag TAG 的设备组命令上，--folder ID 都会选择该文件夹及其内部每个文件夹中的所有活动屏幕。活动也一样：在 campaign create 和 campaign update 上使用 --folder ID，或在 --audience 中使用 {"folder":"sfd_…"} 规则，并可像 {"all":[{"folder":"sfd_BUILDING"},{"tag":"overhead"}]} 那样与标签规则组合。

文件夹的默认播放列表是其屏幕在没有自己的播放列表时显示的内容。位于屏幕上方、设置了默认播放列表的最近文件夹优先，effective_playlist 报告 source 为 folder，并以文件夹 ID 作为 entry_id。接管、活动、排程以及屏幕自身分配的播放列表的优先级都高于它；见 排程和接管。播放列表必须已批准（playlist_not_approved，退出码 5）。

移动屏幕或文件夹，或更改文件夹的默认播放列表，会在约 15 秒内重新解析受影响的屏幕。响应中的 levels 在 gained 和 lost 下列出这些屏幕加入或离开了其文件夹受众的活动，以及它们开始或停止显示的文件夹默认播放列表，每项带有其 source（campaign 或 folder）、id 和 screens 数量。删除文件夹不会删除其中的任何内容：其屏幕和文件夹会上移到父文件夹，而只要有活动受众指向该文件夹，resource_conflict（退出码 5）就会拒绝删除。删除响应返回 200，并带有 levels，与移动时一样。

写入需要管理权限：提议会话返回 403 insufficient_access。涉及受保护文件夹的更改会等待第二位审批人，并返回 pending_review；--note TEXT 可向审批人说明原因。每次写入都会向项目事件附加 screen.folder_created、screen.folder_updated、screen.folder_deleted 或 screen.moved。

其他命令组