CLI 命令参考

读取项目记录及其剩余额度。

project show

无参数。

screenrig project show

data.credit_remaining 是整数额度。低于 1000 时信封可能带有 credits_low 警告。2027 年 1 月 1 日前，合理范围内的使用免费，因此剩余额度只是智能体可读取的整数计量，而不是停用指令。

设置人们在仪表板项目切换器中看到的名称。

project rename NAME

读取项目计划、独立的 screens 和 advertiser 功能标志及有效能力集。路由拒绝优先于过时的能力读取。

project capabilities

读取项目在 UTC 天数上的每日屏幕可用性。

project uptime [--day-from YYYY-MM-DD] [--day-to YYYY-MM-DD]

screenrig project uptime
screenrig project uptime --day-from 2026-09-01 --day-to 2026-09-30

范围和默认值与 screen uptime 相同。data.items 按 UTC 天列出一行，最旧在前：online_s 和 offline_s 汇总当天有记录状态的屏幕，availability、coverage（这些屏幕当天有记录状态的时间份额）和 screens（有记录状态的屏幕数量）。当天行覆盖已结束的区间；screen list 显示当前在线人员。

按 UTC 小时读取机群健康状况：报告的屏幕、热点、显示器断开、崩溃。

project health-trend [--from TIME] [--to TIME]

screenrig project health-trend
screenrig project health-trend --from 7d

data.items 按 UTC 小时列出车队健康状况：hour、screens_reporting、hot（峰值温度达到或超过 80 °C）、display_disconnected 和 crashing（24 小时内 3 次或以上崩溃）。CLI 跟踪 next_cursor 至结束，并每小时响应 next_cursor null。小时报告最多延迟约 5 分钟。

创建、列出或撤销项目成员和广告买家邀请。

invitations create --email ADDRESS[,ADDRESS] [--kind member|ad-buyer]
invitations create --link
    [--screen-id ID] [--slot-id ID] [--policy trusted|review_required]
invitations list [--kind member|ad-buyer] [--status STATUS]
invitations revoke ID

--kind 默认为 member。电子邮件发送为默认方式，七天后过期。--email 支持逗号分隔的收件人，每次最多五十个。--link 仅限成员，需指定一位收件人，返回一次性有效 24 小时的邀请链接用于直接转交。请勿将该链接写入日志、备注或共享记录。列表操作不会返回该链接。

广告买家仅使用电子邮件，需要拥有屏幕或广告位权限（或两者）。--screen-id 和 --slot-id 接受逗号分隔的 ID；--policy 选择 trusted 或 review_required。状态筛选器包括 queued、sent、issued、accepted、revoked、expired 和 failed。

screenrig invitations create --email teammate@example.com
screenrig invitations create --kind ad-buyer --email buyer@example.com --screen-id scr_LOBBY --policy review_required

智能体不接受邀请。被邀请者打开邮件，登录或创建通行密钥，并在控制台接受。链接注册先验证其邮箱。撤销已接受的邀请不会取消成员身份；请使用买家成员控制撤销广告访问权限。

报告此安装是否持有可用凭证。

agent status

无参数。

screenrig agent status

只读。永不更改本地或服务器状态，且无任何费用。结果包含会话的 access、其 effective_access，以及当项目审核设置或无审批权限成员持有较低权限时的 access_limited_by（project 或 person）。

在控制台中获得某人批准后，将此安装登录到现有账户。

login [--project ID] [--access read|propose|manage] [--name NAME] [--no-wait] [--resume ID]

screenrig login --access read

打印控制台地址和一个八字母代码到标准错误，然后等待最长 24 小时。人员检查代码是否匹配，并按一次连接，最近一小时内登录控制台后无第二次通行密钥提示。信封报告 status: signed_in、项目、组织和 access。在已登录安装上再次运行会添加项目或将只读或提议项目提升为管理。拒绝为 login_denied，过期为 login_expired。

结束此安装的登录并移除其令牌。

logout

无参数。

screenrig logout

撤销服务器上的登录，然后移除存储的令牌并报告 status: signed_out。可能未到达服务器的失败将保留令牌，因此重新运行是安全的。运行 screenrig login 重新登录。

打开普通控制台 URL。此命令不生成登录链接、不创建会话，也不需要智能体凭证。

dashboard [open]

screenrig dashboard

控制台在登录后显示该人的项目。浏览器项目选择不更改绑定到智能体的项目。

请求无代理凭证的登录重置邮件。

dashboard reset-sign-in --email ADDRESS

确认不会透露电子邮件是否有登录。邮件重置一小时后过期；用户创建新通行密钥。完成后替换登录凭据并撤销其他会话。

检查此安装并按名称报告每次检查。

doctor [--repair-config]

screenrig doctor

data.checks 命名每个检查及其状态：Node 运行时、解析的配置路径及其权限、控制平面来源及其服务路由、公布的 feedback 能力，以及可选的媒体工具链（ffmpeg、ffprobe、encoder_libx264、encoder_libx265、encoder_libwebp、cwebp、filter_hdr_tonemap）。

任何失败的检查都会使doctor非零退出，因此在调用安装为不健康之前请读取各个名称。缺失的媒体工具链仅影响media upload。

打印捆绑的 CLI 版本及其协议适配器。

version

无参数。

screenrig version

会话中先运行此命令。成功的信封证明启动器已解析捆绑的 CLI。--version 和 -V 可在命令行任何位置执行相同操作。

列出该项目的服务客户端，包括有效和已撤销的，及其密钥、秘密 ID 和使用情况。

service-client list

无参数。

screenrig service-client list

永不返回秘密。

显示一个服务客户端。

service-client show ID

screenrig service-client show scl_ID

列出每个密钥的 kid 和每个秘密的 css_ ID 以便轮换。

创建此项目拥有的服务客户端。

service-client create --name NAME [--capability NAME]... [--access read|propose|manage] [--key-file PATH] [--secret-file PATH]

screenrig service-client create --name "Nightly report" --access read --capability reports --key-file screenrig-client.pem

需要上述身份、项目和组织管理员权限。每个组织跨其所有项目最多有 50 个有效客户端。没有自身 kid 的密钥通过其 RFC 7638 指纹识别。

注册第二个公钥以实现无停机轮换。

service-client add-key ID --key-file PATH

screenrig service-client add-key scl_ID --key-file new.pem

客户端最多持有两个密钥。

生成第二个密钥以实现无停机轮换。

service-client add-secret ID --secret-file PATH

screenrig service-client add-secret scl_ID --secret-file new-secret

客户端最多持有两个密钥。当前密钥在移除前持续有效。

移除密钥；使用该密钥签发的令牌将在几秒内失效。

service-client remove-key ID --kid KID

screenrig service-client remove-key scl_ID --kid KID

客户端至少保留一个密钥或密钥。

移除密钥秘密；使用该秘密签发的令牌将在几秒内失效。

service-client remove-secret ID --secret-id css_ID

screenrig service-client remove-secret scl_ID --secret-id css_ID

永久撤销服务客户端。

service-client revoke ID --yes

screenrig service-client revoke scl_ID --yes

删除其密钥和秘密；其令牌在几秒内停止工作。记录保留以供审计。

生成可展示的整页静态图像并存储到项目媒体库。

media generate --prompt TEXT [--aspect-ratio RATIO] [--quality low|medium|high] [--tag TAG]
               [--no-progress]

screenrig media generate --prompt "A 16:9 restaurant menu poster for North Lobby Cafe. Dark walnut, gold type. Title NORTH LOBBY CAFE. Items: Espresso $4, Cortado $4.50, House Blend $3. Footer Open 7am to 7pm. Typeset every line of copy in the image." --aspect-ratio 16:9 --quality high --tag LobbyMenu

命令将有损 WebP 存储在项目媒体库并返回 data.media_id（med_…）。请勿重新上传字节。切勿打印像素或提示。创作树和提示合同保存在 Compose。

将本地文件转换为传输字节，上传并等待对象准备就绪。

media upload <file> [--content-type TYPE] [--tag TAG] [--folder ID] [--no-wait] [--poll-ms MS]
             [--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
             [--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
             [--preset signage-1080p30|signage-4k30] [--no-audio]

screenrig media upload ./lobby-welcome-loop.mp4 --tag LobbyLoop

视频默认转为 MP4：H.264 高级配置文件 4.2，或带 --codec hevc 的 H.265，标记为 yuv420p Rec. 709。HDR 源映射至 Rec. 709。音频（若有）为 AAC，192 kbit/s，48 kHz，立体声。

静态图像在质量 90 时变为有损 WebP，保留源图像的透明通道。动画源无限循环。已符合大小限制的 WebP 直接传递，不重新编码。

音频变为播放列表配乐的 MP3。MP3 源保持不变上传；WAV、AAC、M4A、OGG 和 FLAC 源转换为 128 kb/s MP3，需带 libmp3lame 的 ffmpeg 构建。曲目时长 1 秒至 3 小时。playlist init 将音频输入变为配乐曲目而非页面。准备好的对象是带时长的 audio 媒体对象。不能放置在页面上；在播放列表中命名为 audio 配乐。

准备就绪的对象 ID 是 data.media_id。相同的值是 data.id 和 data.operation.result.media_id。该 ID 是播放列表选择器使用的。

低信息量文件名如 video.mp4 会在信封中添加建议性 generic_filename 警告。上传仍成功，CLI 不会重命名文件；请在运行命令前选择名称。

转换运行 ffmpeg 和 ffprobe，来源于 PATH，或来自 SCREENRIG_FFMPEG 和 SCREENRIG_FFPROBE 中的绝对路径。静态图像优先使用 ffmpeg libwebp 编码器，遇 PATH 或 SCREENRIG_CWEBP 时回退到 cwebp。会话首次上传前运行 doctor。

--preset signage-1080p30 将长边限制为 1920，短边限制为 1080，帧率恒定为 30 fps。signage-4k30 将长边限制为 3840，短边限制为 2160，帧率恒定为 30 fps。两者均支持横屏、竖屏和方形内容。--no-audio 对静音片段不进行音频编码。这些选项仅适用于视频。

screenrig media upload ./lobby.mov --preset signage-1080p30 --no-audio

screenrig media upload ./menu.png --folder mfd_01EXAMPLEFOLDER000000000

上传文件先到达库根目录，准备好后移入文件夹。media upload-batch --folder 同样处理每个上传项。

在提议访问权限下，或项目要求审核代理更改时，新上传内容需等待人工审核后，标签、文件夹或all选择器才能播放；详见审核。

从清单上传多个本地文件，可从所需状态文件恢复。

media upload-batch <manifest.json> [--state FILE] [--concurrency N] [--tag TAG] [--folder ID]
                   [--poll-ms MS] [--timeout MS] [--no-transcode] [--codec h264|hevc]
                   [--max-fps N] [--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
                   [--preset signage-1080p30|signage-4k30] [--no-audio]

screenrig media upload-batch ./images.json --state ./upload-state.json

信封按清单顺序携带 data.items[]，每个包含 path、source_filename、sha256、outcome（accepted 或 resumed）和 media_id。data.failed[] 携带未落地的项目。

就地替换媒体的文件。其 ID、播放列表和日程继续有效。

media replace <id> <file> [--expect-rev REVISION] [--note TEXT] [--content-type TYPE] [--no-wait]
              [--poll-ms MS] [--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
              [--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
              [--preset signage-1080p30|signage-4k30] [--no-audio]

screenrig media replace med_01EXAMPLEIMAGE0000000000 ./menu-v2.png
screenrig media replace med_01EXAMPLEVIDEO0000000000 ./intro.mp4 --expect-rev 3 --note "Spring cut"

媒体保留其 ID、标签和文件夹，因此引用它的每个播放列表和日程会在下一个清单中播放新文件，标签、文件夹和 all 选择器也会随之更新。无需重新安排任何内容。该命令执行与 media upload 相同的步骤（转换、套餐的视频字节上限、尺寸上限、存储额度、签名传输），然后进行替换而不是添加新媒体。它不接受 --tag 或 --folder。

默认情况下，命令会等待处理完成。data.media_id 和 data.id 是媒体 ID，data.version 是新文件在 media versions 中的编号，data.revision 是媒体的新修订。data.warnings、data.operation、data.upload、data.transcode 和耗时的报告方式与 media upload 相同，操作 ID 位于信封中。使用 --no-wait 时，data.operation 是已接受的操作，data.version 和 data.warnings 不会出现。

允许更改宽高比。信封中带有 aspect_ratio_changed 警告，data.warnings[].playlists 会列出使用该媒体的播放列表，请检查它们的显示效果。与当前文件字节相同的文件会被拒绝，返回 resource_conflict（退出码 13）。

每个先前的文件都保留在媒体的历史记录中，并计入已存储字节，直到其版本被删除；参见 media versions。

在 Propose 访问权限下，或项目要求对代理更改进行审核时，替换会等待人工审核，命令成功返回（退出码 0）：data.status 为 pending_review，data.review_id 指明审核，警告 pending_review 给出其 URL，data.next 为 screenrig reviews show ID。在有人批准之前，媒体继续播放其当前文件，因此请告知对方它正在等待，且不要重复写入。同一媒体较新的替换会取代正在等待的那个。参见审核。

列出媒体曾有的文件，当前使用的文件排在最前。

media versions <id> [--limit N] [--cursor CURSOR]

screenrig media versions med_01EXAMPLEIMAGE0000000000

data.items 为媒体曾有的每个文件提供一个条目：number、current、filename、content_type、sha256、bytes、width、height、duration_ms、codecs、source（upload、replace、sync 或 restore）、note、by（种类为 person、agent、client 或 sync，含 ID 和名称）以及 restored_from。当前使用的文件排在最前（current: true），其余按从新到旧排列。版本 1 是首次上传；每次替换、恢复或媒体同步更改都会增加下一个编号。

不带 --limit 和 --cursor 时会读取所有页面，且 data.next_cursor 为 null。带其中任意一个时只读取一页：只要 data.next_cursor 是字符串，就用设为该值的 --cursor 再次运行命令。只读访问权限即可。过去版本的字节会一直保存并计入项目的已存储字节，直到 media version delete 将其删除；保留的版本数量没有限制，超出套餐免费存储的已存储字节与其他存储一样计费。

将过去的版本作为新版本重新投入使用。

media restore <id> --number N [--expect-rev REVISION] [--note TEXT]

screenrig media restore med_01EXAMPLEIMAGE0000000000 --number 2
screenrig media restore med_01EXAMPLEIMAGE0000000000 --number 2 --expect-rev 5 --note "Back to the winter menu"

媒体保留其 ID 并进入新的修订，引用它的每个播放列表和日程都会再次播放该文件。被复制的版本仍保留在历史记录中并共用其字节；新版本与其他版本一样计入已存储字节。data.media 是媒体，当恢复的文件宽高比不同时，data.warnings 带有 aspect_ratio_changed，列出使用该媒体的播放列表。

当前使用的版本不能恢复（resource_conflict，退出码 5），未知版本为 not_found（退出码 4）。在 Propose 访问权限下，或项目要求对代理更改进行审核时，恢复会等待人工审核，命令成功返回（退出码 0）：data.status 为 pending_review，并带有 data.review，警告 pending_review 给出其 URL，data.next 为 screenrig reviews show ID。在有人批准之前，媒体继续播放其当前文件，因此请勿重复写入。

删除过去的版本及其已存储的字节。

media version delete <id> --number N

screenrig media version delete med_01EXAMPLEIMAGE0000000000 --number 2

该版本的记录被删除，其字节立即从项目的已存储字节中扣除。已存储的对象在 24 小时后被移除，除非另一个版本或当前使用的文件持有同一文件。已删除的版本无法恢复。当前使用的版本不能被删除，并且在媒体的替换等待审核期间，任何版本都不能被删除；这两种情况均为 resource_conflict（退出码 5），media versions ID 会显示哪个版本正在使用。未知版本为 not_found（退出码 4）。删除需要 Manage 访问权限：Propose 凭据会被拒绝并返回 insufficient_access，删除操作绝不会被提交审核。

读取一个媒体对象，包括其当前版本。

media show <id>

screenrig media show med_01EXAMPLEIMAGE0000000000

写入存储的渲染文件以供检查。切勿打印字节。

media download <id> [--output FILE]

screenrig media download med_01EXAMPLEIMAGE0000000000 --output ./lobby.webp

信封报告 media_id、path、bytes、sha256、content_type、primitive、filename，可选 source_filename，以及 width / height。它从不携带像素。用于在生成静态图像上屏前进行校验。

列出媒体对象，可按标签和原始类型筛选。

media list [--tag TAG] [--primitive image|video|audio] [--folder ID|root] [--library]

screenrig media list --tag LobbyLoop --primitive video
screenrig media list --folder mfd_01EXAMPLEFOLDER000000000
screenrig media list --library

每一行都包含 folder_id，但在库根目录下没有。

更改或清除单个对象的标签。其可用性规则通过 media availability 设置。

media update <id> (--tag TAG | --tags TAG1,TAG2 | --clear-tag) [--expect-rev REVISION]

screenrig media update med_01EXAMPLEIMAGE0000000000 --tag LobbyLoop

在提议访问权限下，或项目要求审核代理更改时，重新标记已批准的媒体会以警告media_review_pending回应ok：屏幕继续使用其已批准的标签播放，直到人工批准更改，拒绝则恢复标签。审核结果几秒内显示在reviews list；未更改任何已批准播放列表或待审核播放列表的重新标记自动生效。详见审核。

设置或清除动态选择器何时可以选取某个文件。

media availability <id> (--file FILE | --clear) [--expect-rev REVISION]

screenrig media availability med_01EXAMPLEIMAGE0000000000 --file rule.json

规则的成员和行为见媒体可用性。

删除一个媒体对象。

media delete <id> [--expect-rev REVISION]

screenrig media delete med_01EXAMPLEIMAGE0000000000

将媒体文件和文件夹移动到某个文件夹，或移回库根目录。

media move <id>... (--folder ID | --root)

screenrig media move med_01EXAMPLEIMAGE0000000000 med_01EXAMPLEVIDEO0000000000 --folder mfd_01EXAMPLEFOLDER000000000
screenrig media move mfd_01EXAMPLEFOLDER000000000 --root

移动为全有或全无请求。文件夹不能移动到自身或其内部文件夹，文件夹最多嵌套10层。目标中已有项保持不变。data.media 和 data.folders 统计移动数量。

移动文件会改变其旧文件夹和新文件夹的 by:folder 选择器的播放内容，从每个屏幕的下一个选择器解析开始；移动文件夹不会改变任何文件夹自身的文件。在 Propose access 下，或当项目需要代理变更审核时，每个移动的文件需等待人工审核（reviews list），已批准的播放列表继续按批准时所在文件夹播放；详见 审核。

列出项目的媒体文件夹。

media folder list [--library]

screenrig media folder list
screenrig media folder list --library

返回项目的所有文件夹，最多 1000 个，按名称排序：data.items 包含 id、name、parent_id（null 位于库根目录）和 revision。从 parent_id 构建树。文件的文件夹在 media list 上的 folder_id 和 media show；在库根目录则不存在。

读取一个媒体文件夹。

media folder show <id>

screenrig media folder show mfd_01EXAMPLEFOLDER000000000

信封携带文件夹的 name、parent_id 和 revision。

在库根目录或另一个文件夹内创建媒体文件夹。

media folder create --name NAME [--parent ID]

screenrig media folder create --name Menus
screenrig media folder create --name Lunch --parent mfd_01EXAMPLEFOLDER000000000

组织跨其所有项目最多持有 1000 个文件夹，嵌套深度最多 10 级。播放列表通过 by:folder 选择器播放文件夹中的文件。

重命名媒体文件夹，或将其连同内部所有内容移动到另一个文件夹。

media folder update <id> [--name NAME] [--parent ID | --root] [--expect-rev REVISION]

screenrig media folder update mfd_01EXAMPLEFOLDER000000000 --name Archive
screenrig media folder update mfd_01EXAMPLEFOLDER000000000 --root

文件夹不能移动到自身或其内部的文件夹，且移动必须保持所有文件夹层级不超过 10 级。发送当前值为无操作。

删除媒体文件夹。其文件和文件夹上移一级。

media folder delete <id> [--expect-rev REVISION]

screenrig media folder delete mfd_01EXAMPLEFOLDER000000000

仅删除文件夹。其文件和文件夹上移至其父级，或无父级时上移至库根目录。命名该文件夹的 by:folder 选择器将不匹配任何内容，请先重新指向这些播放列表。

添加您自己的 Microsoft Entra 应用，或项目的 Microsoft 连接，以便同步可以读取 SharePoint 或 OneDrive for work 文件夹。

media sync account add microsoft365 --name NAME
    (--tenant-id TENANT --client-id ID --secret-file FILE | --connection-id ID)

screenrig media sync account add microsoft365 --name Contoso --tenant-id contoso.onmicrosoft.com --client-id 0b1d2f3a-4c5e-4f60-8a7b-9c0d1e2f3a4b --secret-file secret.txt
screenrig media sync account add microsoft365 --name Contoso --connection-id pcn_01EXAMPLECONNECTION0000

在 Microsoft Entra 管理中心注册一个不带重定向 URI 的单租户应用，添加客户端密钥（复制其值，而不是密钥 ID），添加 Microsoft Graph 应用程序权限 Sites.Selected（然后授予该应用对每个站点的读取权限）或 Files.Read.All，并授予管理员同意。该应用属于此项目。接着运行 media sync account test。

添加 Dropbox 账户，并打印其所有者在登录 Dropbox 后打开以完成连接的一次性链接。

media sync account add dropbox --name NAME [--app-key KEY]

screenrig media sync account add dropbox --name "Marketing Dropbox"
screenrig media sync account add dropbox --name "Marketing Dropbox" --app-key YOURAPPKEY

data.authorize_url 是链接，data.authorize_expires_at 是其到期时间。CLI 绝不会打开浏览器：请把链接发给 Dropbox 账户的所有者，由其允许只读访问（files.metadata.read、files.content.read、account_info.read）。运行 media sync account show，直到 data.state 变为 ready（初始为 pending_consent），然后运行 media sync create dropbox。您自己的 Dropbox 应用需要启用这些权限，并添加输出中打印的重定向 URI。

添加 Google Drive 账户，立即可用，并打印用于共享文件夹的服务账号地址。

media sync account add google-drive --name NAME [--key-file FILE]

screenrig media sync account add google-drive --name "Marketing Drive"
screenrig media sync account add google-drive --name "Marketing Drive" --key-file key.json

data.config.service_account_email 是要与每个文件夹共享的地址；Viewer 权限即可。通过 screenRIG 的服务账号，只有当此项目中邮箱已验证的成员共享或拥有该文件夹时，它才会同步（否则为 media_sync_sharer_not_member）。使用您自己的密钥时，任何与该服务账号共享的文件夹都会同步。

列出此项目的媒体同步账户，并显示其类型、状态和最近一次测试；不会返回任何密钥。

media sync account list

无参数。

screenrig media sync account list

查看一个账户：其租户和客户端 ID、状态、屏蔽后的密钥和最近一次测试。

media sync account show <id>

screenrig media sync account show msa_01EXAMPLEACCOUNT0000000

Dropbox 账户还会显示是谁连接了它以及其 app_key；Google Drive 账户显示其 service_account_email。

重命名账户，更改 Microsoft 应用的租户、应用程序 ID 或客户端密钥，或替换 Google Drive 账户自己的密钥。

media sync account update <id> [--name NAME] [--tenant-id TENANT] [--client-id ID]
    [--secret-file FILE | --key-file FILE] [--expect-rev REVISION]

screenrig media sync account update msa_01EXAMPLEACCOUNT0000000 --secret-file new-secret.txt
screenrig media sync account update msa_01EXAMPLEACCOUNT0000000 --name "Contoso tenant" --expect-rev 2

至少需要一项更改。更改凭据会清除 last_test：请重新测试该账户。Entra 客户端密钥会过期，因此请在其过期之前在此替换密钥。

生成新的一次性链接，用于连接或重新连接 Dropbox 账户。

media sync account connect <id>

screenrig media sync account connect msa_01EXAMPLEACCOUNT0000000

data.authorize_url 和 data.authorize_expires_at 带有该链接，它会取代之前的链接。把它发给 Dropbox 账户的所有者。当对方没有完成授权，或账户为 reconnect_required（Dropbox 不再认可该连接）时使用。已连接的账户在新的授权完成之前保持连接，而另一个 Dropbox 账户登录后会接管该连接。

检查账户：Microsoft 应用的登录和 Graph 权限，或 Dropbox 或 Google Drive 账户的连接或密钥。

media sync account test <id>

screenrig media sync account test msa_01EXAMPLEACCOUNT0000000

响应存储为 last_test。对于 Microsoft 应用，它报告 credentials（Microsoft 已签发令牌；被拒绝时会带有其 AADSTS 代码，例如密钥是 ID 而不是值时的 AADSTS7000215）和 permissions（令牌带有的 Graph 应用程序权限）。仅有 Sites.Selected 则为警告：每个站点仍然需要单独授予，共享链接则需要 Files.Read.All。该测试不判定站点的授权或某个文件夹：media sync create 会读取您指定的文件夹。检查失败时，data.ok 为 false，退出码为 0。

删除没有任何同步使用的账户。

media sync account delete <id> [--expect-rev REVISION]

screenrig media sync account delete msa_01EXAMPLEACCOUNT0000000

只要有同步使用该账户，响应就是 resource_conflict（退出码 5），并指明它们：请先删除这些同步。

将 SharePoint 或 OneDrive for work 文件夹同步到媒体文件夹。

media sync create sharepoint --account-id ID --url URL [--folder-id ID] [--every DURATION] [--name NAME]

screenrig media sync create sharepoint --account-id msa_01EXAMPLEACCOUNT0000000 --url https://contoso.sharepoint.com/sites/Marketing/Shared%20Documents/Lobby%20Signs
screenrig media sync create sharepoint --account-id msa_01EXAMPLEACCOUNT0000000 --url "https://contoso.sharepoint.com/:f:/s/Marketing/EabcDEF" --folder-id mfd_01EXAMPLEFOLDER000000000 --every 1h --name "Lobby signs"

Microsoft 拒绝的文件夹会返回 media_sync_source_refused（退出码 5），并附带需要授予的权限；不会存储任何内容。

将 Dropbox 文件夹同步到媒体文件夹。

media sync create dropbox --account-id ID --url URL|PATH [--folder-id ID] [--every DURATION] [--name NAME]

screenrig media sync create dropbox --account-id msa_01EXAMPLEACCOUNT0000000 --url https://www.dropbox.com/home/Marketing/Lobby%20Signs
screenrig media sync create dropbox --account-id msa_01EXAMPLEACCOUNT0000000 --url /Marketing/Lobby --folder-id mfd_01EXAMPLEFOLDER000000000 --every 1h --name "Lobby signs"

每次运行都从 Dropbox 在该文件夹中保存的位置继续，只读取发生变化的内容。账户无法打开的文件夹为 media_sync_source_refused，Dropbox 不再认可的连接为 dropbox_reconnect_required（media sync account connect）：两者的退出码均为 5，不存储任何内容。

将与账户的服务账号共享的 Google Drive 文件夹同步到媒体文件夹。

media sync create google-drive --account-id ID --url URL|ID [--folder-id ID] [--every DURATION] [--name NAME]

screenrig media sync create google-drive --account-id msa_01EXAMPLEACCOUNT0000000 --url https://drive.google.com/drive/folders/1AbCdEfGhIjKlMnOpQrStUvWxYz --folder-id mfd_01EXAMPLEFOLDER000000000 --every 1h
screenrig media sync create google-drive --account-id msa_01EXAMPLEACCOUNT0000000 --url 1AbCdEfGhIjKlMnOpQrStUvWxYz

通过 screenRIG 的服务账号，只有当此项目中邮箱已验证的成员共享或拥有该文件夹时，它才会同步（media_sync_sharer_not_member，退出码 3，不存储任何内容）。每次运行都会重新检查这一点，失去这样的共享者的文件夹会使同步停在 error 状态，并保留其媒体：请从成员的 Google 账号重新共享，然后运行 media sync update ID --resume。Google Docs、Sheets 和 Slides 文件会作为 unsupported_type 被跳过。地址无法打开的文件夹为 media_sync_source_refused（退出码 5）：请将其共享给该服务账号。

列出此项目的媒体同步，并显示其媒体文件夹、频率、状态和最近一次运行的状态。

media sync list

无参数。

screenrig media sync list

查看一个同步及其最近一次运行的摘要。

media sync show <id>

screenrig media sync show msy_01EXAMPLESYNC000000000

data.last_run 带有 status（ok、partial 或 error）、added、updated、removed、pending_delete（屏幕仍持有的已移除文件，在 Removed 文件夹中等待）以及 skipped（附每个文件的原因：unsupported_type、too_large、storage、subfolder、download_failed、unreadable、in_use）；失败的运行带有 error，其中的 code 和 detail 会指明修复方法。data.source 为 Dropbox 增加 path，为 Google Drive 增加 shared_by。

状态为 error 的同步需要修复。其媒体文件夹已被删除：用 media sync update --folder-id 将其指向另一个文件夹。其来源文件夹已被删除或移动：删除该同步并创建一个新的。对于通过 screenRIG 服务账号使用的 Google Drive，该文件夹失去了已验证的共享者（sharer_not_member）：请从项目成员的 Google 账号重新共享，然后运行 media sync update ID --resume。当 Dropbox 不再认可该连接（media sync account connect）时，Dropbox 运行会以 reconnect_required 失败。

更改同步的名称、频率或媒体文件夹，或暂停和恢复它。

media sync update <id> [--name NAME] [--every DURATION] [--folder-id ID]
    [--pause | --resume] [--expect-rev REVISION]

screenrig media sync update msy_01EXAMPLESYNC000000000 --every 1h
screenrig media sync update msy_01EXAMPLESYNC000000000 --pause
screenrig media sync update msy_01EXAMPLESYNC000000000 --folder-id mfd_01EXAMPLEFOLDER000000000 --expect-rev 3

至少需要一项更改。

立即运行同步，而不是等到下一次运行时间。

media sync run <id>

screenrig media sync run msy_01EXAMPLESYNC000000000

同步会在大约 30 秒内运行，之后 media sync show 会显示其最近一次运行。已暂停的同步必须先恢复。

停止同步；其媒体和文件夹会保留。

media sync delete <id> [--expect-rev REVISION]

screenrig media sync delete msy_01EXAMPLESYNC000000000

同步会忘记哪个来源文件对应哪个媒体。已导入的媒体和媒体文件夹会保留，不会移除任何内容。

将静态目录打包成确定性归档，无需上传。

app pack <directory> [--output FILE]

screenrig app pack ./lobby-board --output ./lobby-board.tgz

信封报告 sha256、compressed_bytes、expanded_bytes、file_count、条目列表，以及 SDK 运行时是否被注入。app upload 打包目录本身，仅在想先检查归档时使用此命令。

应用运行在阻止内联代码的内容安全策略下。打包会将内联样式和脚本块移入 _screenrig/inline/ 下的文件并链接。内联事件处理器如 onclick= 和 javascript: URL 无法移动；打包拒绝它们并标明文件和行号。

打包目录，发布为新应用版本，等待发布成功。

app upload <directory> [--name NAME] [--no-wait] [--poll-ms MS] [--timeout MS]

screenrig app upload ./lobby-board --name "Lobby board"

读取三个字段：data.operation.state 是 succeeded，data.application.release_id 是 rel_ ID，一个 application 原语引脚，data.application.id 是 app_ ID，kv 命令使用。成功操作（非单独的发布 ID）表示发布可用。

每个 app upload 创建一个新应用和第一个不可变版本。发布同一应用的后续版本，使用 app update。播放列表保持提供已固定的版本，直到编辑该原始版本。

发布现有应用的新版本，保留身份、名称和应用 K/V。

app update <id> <directory> [--expect-rev REVISION] [--no-wait] [--poll-ms MS]

screenrig app update app_01EXAMPLEAPP00000000000 ./lobby-board

等待 data.operation.state: "succeeded"，然后使用 playlist replace-release 审查确切的页面、原语、新版本和受影响的屏幕。使用返回的影响令牌和可选的修订保护（如 播放列表工作流 中所述）进行应用。现有播放列表固定保持不变直到应用。遇到修订冲突时，重新读取应用后再决定是否重试；不要为了绕过冲突而创建替代应用。

列出项目的应用程序。

app list

无参数。

screenrig app list

读取一个应用。

app show <id>

screenrig app show app_01EXAMPLEAPP00000000000

latest_ready_release 在首次发布达到就绪前不会出现。发布状态属于操作和发布版本，不属于应用。

删除一个应用及其所有版本。

app delete <id> [--expect-rev REVISION]

screenrig app delete app_01EXAMPLEAPP00000000000

无单独的发布删除。当屏幕显示应用的某个发布时，删除返回 application_in_use：请先给这些屏幕其他内容。删除不检查固定发布但未显示的播放列表，因此也需更新或删除这些播放列表。

列出为一个应用程序存储的密钥。

kv list --app-id ID

screenrig kv list --app-id app_01EXAMPLEAPP00000000000

读取一个密钥。

kv get --app-id ID <key>

screenrig kv get --app-id app_01EXAMPLEAPP00000000000 menu

从 JSON、文件或 base64 字节写入一个密钥。

kv set --app-id ID <key> --json-value JSON [--expect-rev REVISION]
kv set --app-id ID <key> --file FILE [--content-type TYPE] [--expect-rev REVISION]
kv set --app-id ID <key> --value-base64 BASE64 [--content-type TYPE] [--expect-rev REVISION]

screenrig kv set --app-id app_01EXAMPLEAPP00000000000 menu --json-value '{"soup":"lentil"}'

删除一个键。

kv delete --app-id ID <key> [--expect-rev REVISION]

screenrig kv delete --app-id app_01EXAMPLEAPP00000000000 menu

创建一个写入单个密钥的 webhook，并一次性获取其 URL 和密钥。

kv webhook create <key> --app-id ID [--description TEXT]

screenrig kv webhook create menu --app-id app_01EXAMPLEAPP00000000000 --description "Point of sale menu feed"

信封是 webhook：data.id（kvw_…）、data.key、data.url（https://api.screenrig.ai/api/applications/<app_id>/kv-webhooks/<id>/write）和 data.secret（srkw_…）。请立即在发送系统中输入 URL 和密钥。后续命令不会再次显示该密钥。

列出应用程序的 webhook，最旧优先。

kv webhook list --app-id ID

screenrig kv webhook list --app-id app_01EXAMPLEAPP00000000000

每个项目都有 id、key、description、url、created_at，写入后还有 last_used_at。列表从不包含密钥。

删除 Webhook。其 URL 立即停止工作，且密钥保持其值。

kv webhook delete <webhook_id> --app-id ID

screenrig kv webhook delete kvw_01EXAMPLEWEBHOOK00000 --app-id app_01EXAMPLEAPP00000000000

替换Webhook密钥并仅接收一次新密钥。

kv webhook rotate-secret <webhook_id> --app-id ID

screenrig kv webhook rotate-secret kvw_01EXAMPLEWEBHOOK00000 --app-id app_01EXAMPLEAPP00000000000

信封在 data.secret 中携带新密钥。旧密钥立即失效，请在发送系统中输入新密钥。

更改卡片 webhook：其描述、映射、启用状态或签名。

kv webhook update <webhook_id> --card CARD_ID [--description TEXT] [--map FILE|-] [--clear-map]
                   [--enable|--disable] [--signing|--no-signing]

screenrig kv webhook update kvw_01EXAMPLEWEBHOOK00000 --card crd_01EXAMPLEBOARD0000000000 --map alert-map.json

信封即该 webhook。data.signing_secret 只出现一次，在开启签名的那次响应中。

读取卡片 webhook 过去七天的投递日志，最新的在前。

kv webhook deliveries <webhook_id> --card CARD_ID [--limit N]

screenrig kv webhook deliveries kvw_01EXAMPLEWEBHOOK00000 --card crd_01EXAMPLEBOARD0000000000

每一项包含 at、outcome（written、unchanged、refused、invalid 或 handshake）、reason（例如 credentials、signature、disabled、body、mapping、card_data_invalid 或 rate_limited）、detail、status、bytes、revision 和 request_id。不会存储正文、请求头或凭据，向错误地址发送的请求不会留下任何记录。

从本地媒体文件、准备好的媒体ID、应用发布ID或HTTP 或 HTTPS URL准备可编辑的全屏播放列表。

playlist init <inputs...> --name NAME --output FILE [--overwrite] [--screen-id ID]
              [--target-width PX --target-height PX] [--duration-ms MS] [--fit contain|cover|fill]
              [--no-transcode] [--no-progress] [--poll-ms MS]

screenrig playlist init med_POSTER med_VIDEO --name "Lobby loop" --screen-id scr_LOBBY --output lobby.json

准备写入本地文档并可能上传媒体；不创建远程播放列表或分配屏幕。检查文档，然后screen publish。参见准备、发布和编辑播放列表。

在创建或更新前本地验证播放列表文档。无需网络。

playlist validate <file>

screenrig playlist validate ./lobby-loop.json

错误精确指明 JSON 路径。通过表示本地结构和跨字段语义有效；授权、媒体准备、动态选择器计数、持续时间和远程可用性仍需服务器检查。创建和更新在写入前执行此检查。结果还带有不会使检查失败的几何 lint 发现项：motion_overuse、collision、safe_margin 和 adjacent_repeat。要查看页面外观，请发布它并运行 screen screenshot。

根据 JSON 文档、模板或内置的“紧急通知”模板创建播放列表。

playlist create [file] [--from-template ID --name NAME [--set NAME=VALUE...] [--dry-run]] [--starter KEY [--name NAME]] [--format-region REGION --format-orientation ORIENTATION] [--note TEXT]

screenrig playlist create ./lobby-loop.json

screenrig playlist create --from-template pl_01EXAMPLETEMPLATE00000 --name "Monday notice" --set headline="Open late"

信封中的 data.id 是 screen assign 所接受的 pl_ ID。当更改等待审阅时，data 为 {status: pending_review, review, playlist}：播放列表已存在且 approved_revision: 0，在有人批准前任何屏幕都无法显示它（playlist_not_approved）。模板是声明了 fields 的播放列表，不会显示在屏幕上（playlist_is_template）；由它创建的播放列表是普通播放列表，可分配、排程和修订。

替换播放列表文档。

playlist update <id> <file> [--format-region REGION --format-orientation ORIENTATION] [--expect-rev REVISION] [--note TEXT]

screenrig playlist update pl_01EXAMPLEPLAYLIST000000 ./lobby-loop.json

当更改等待审核时，直播播放列表保持不变，直到有人批准提议。

读取一个播放列表，包括其当前版本。

playlist show <id>

screenrig playlist show pl_01EXAMPLEPLAYLIST000000

返回实时版本。approved_revision 对于无人批准的播放列表为 0，等待变更时 approval 显示开放审核，reviews show ID 返回提案。

列出项目的播放列表。

playlist list [--templates] [--library]

screenrig playlist list --templates
screenrig playlist list --library

显示模板的字段或副本的值，或更改值并使副本保持最新。

playlist fields <id> [--set NAME=VALUE...] [--clear NAME...] [--refresh] [--expect-rev REVISION] [--note TEXT]

screenrig playlist fields pl_01EXAMPLECOPY00000000 --set headline="Closed today"

不带选项时，显示模板的字段及由其创建的播放列表数量，或副本的值、其所基于的模板修订版以及模板是否有更新的修订版。每次更改以及单独使用 --refresh，都会根据模板的当前修订版重新生成副本的页面，对模板所做的品牌变更正是这样传到现有副本的；不会自动推送。值的检查方式与创建时相同。在 Propose 访问下，更改会成为审阅。

列出由模板创建的播放列表及各自所基于的模板修订版。

playlist instances <id>

screenrig playlist instances pl_01EXAMPLETEMPLATE00000

outdated 表示由模板的较旧修订版创建的播放列表；playlist fields ID --refresh 可使其保持最新。

列出播放列表的各个版本，最新的在前。

playlist revisions <id> [--after CURSOR]

screenrig playlist revisions pl_01EXAMPLEPLAYLIST000000

每个版本都说明由什么产生（created、edited、附带所复制版本的 promoted，或 baseline，即播放列表在其历史开始时所处的版本）、由谁产生、何时产生、包含多少页面以及是否为当前版本。每页包含 50 个版本；next_cursor 读取下一页。

读取一个版本以及该版本时的播放列表。

playlist revision show <id> --revision N

screenrig playlist revision show pl_01EXAMPLEPLAYLIST000000 --revision 3

将较早的版本复制为新版本，使其重新成为当前版本。

playlist promote <id> --revision N --expect-rev CURRENT

screenrig playlist promote pl_01EXAMPLEPLAYLIST000000 --revision 3 --expect-rev 9

该版本的页面、配乐和格式成为下一个版本。名称保持不变，较早的版本仍保留在列表中，所有显示该播放列表的屏幕都会更新。提升需要可直接发布的凭据；变更需等待审核的凭据会得到 forbidden。内容已是当前内容的版本不会产生任何变化。

删除一个播放列表。

playlist delete <id> [--expect-rev REVISION]

screenrig playlist delete pl_01EXAMPLEPLAYLIST000000

将图像和视频文件、背景音轨音频以及 iframe URL 导出为可移植的播放列表包。

playlist export <id> --output DIRECTORY [--skip-applications]

screenrig playlist export pl_01EXAMPLEPLAYLIST000000 --output ./lobby-bundle

包中包含清单、播放列表文档，以及按内容寻址的图像、视频和背景音轨音频文件。动态选择器 all、tag 和 folder 会固定为确切的 ID，iframe URL 会保留，注释会被排除。

卡片、流和 adslot 页面会在下载媒体前阻止导出。应用程序默认也会阻止导出；--skip-applications 会移除应用程序基元，以及空页面或由应用程序控制的页面，并报告已跳过的基元和页面 ID。必须至少保留一个页面。使用此标志时，卡片、流和 adslot 页面仍会阻止导出。

如需保留卡片和应用程序引用的可编辑文档，请使用 screenrig playlist show pl_01EXAMPLEPLAYLIST000000 --output playlist.json。该文档使用同一项目中的现有资源。

从捆绑目录创建播放列表，或从中更新现有播放列表。

playlist import <directory> [--name NAME] [--update ID [--expect-rev REVISION] [--note TEXT]]

screenrig playlist import ./lobby-bundle
screenrig playlist import ./lobby-bundle --name "Lobby loop (copy)"

播放列表显示名称可能重复。导入时即使名称相同也会创建独立播放列表；使用带 ID 的 --update 替换现有播放列表。

导入在触及项目之前本地验证整个包：清单、文档、路径、媒体类型、长度和哈希。现有媒体在文件名、媒体类型、字节长度、哈希和标签完全匹配时重用；其余无转换上传，且仅在所有对象准备好后写入播放列表。

导入绝不删除或修剪远程媒体。如果上传开始后后续步骤失败，错误会列出确认准备好的对象，并说明播放列表写入是否开始。重试同一包会重用这些对象。

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

screenrig screen pair "$PAIRING_CODE" --name "Lobby"

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

screen list [--state archived] [--tag TAG] [--folder ID|root]

screenrig screen list --tag Lobby
screenrig screen list --folder sfd_01EXAMPLEFOLDER000000000

每一行都包含该屏幕的 tags。有了 --human，当任意列出的屏幕有标签时，表格会增加一个 TAGS 列。

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

screen show <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；这些判定不涉及的内容见通知。

一次调用即可补丁屏幕名称、播放列表分配或时区。

screen update <id> [--name NAME] [--playlist-id ID] [--timezone ZONE] [--expect-rev REVISION]

screenrig screen update scr_01EXAMPLESCREEN00000000 --name "Lobby"

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

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

screen publish <id> <file> [--expect-rev REVISION] [--note TEXT]

screenrig screen publish scr_LOBBY lobby.json

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

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

screen assign (<id>... | --tag TAG) --playlist-id ID [--expect-rev REVISION] [--note TEXT]

screenrig screen assign scr_01EXAMPLESCREEN00000000 --playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen assign --tag Lobby --playlist-id pl_01EXAMPLEPLAYLIST000000

如果播放列表调度任何页面且屏幕无时区，CLI 在发送任何内容前拒绝并提示运行 screen set-timezone 命令。拒绝不消耗版本。车队中，每个屏幕独立应用该规则：无时区屏幕结果失败，其他屏幕被分配。

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

设置排程播放列表读取的民用时区。

screen set-timezone <id> --timezone ZONE [--expect-rev REVISION]

screenrig screen set-timezone scr_01EXAMPLESCREEN00000000 --timezone America/Los_Angeles

页面计划是民用时间，没有时区则无意义。更改时区会重新铸造清单修订。

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

screen archive <id> [--expect-rev REVISION]

screenrig screen archive scr_01EXAMPLESCREEN00000000

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

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

screen unarchive <id> [--expect-rev REVISION]

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 <id> --message TEXT [--expect-rev REVISION]

screenrig screen suspend scr_01EXAMPLESCREEN00000000 --message "Closed for stocktake. Back at 9am."

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

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

screen resume <id> [--expect-rev REVISION]

screenrig screen resume scr_01EXAMPLESCREEN00000000

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

删除屏幕。

screen delete <id> [--expect-rev REVISION]

screenrig screen delete scr_01EXAMPLESCREEN00000000

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

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

screen replace <id> --with ID [--expect-rev REVISION]

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）的替换播放器。请求始终携带幂等键，完全相同的重试会返回原始响应。

为屏幕发放新的公共 ID。

screen rotate-public-id <id> [--expect-rev REVISION]

screenrig screen rotate-public-id scr_01EXAMPLESCREEN00000000

创建屏幕的链接或替换它，并打印其 Player URL。

screen link create <id> [--expect-rev REVISION]

screenrig screen link create scr_01EXAMPLESCREEN00000000

打印 data.url，即要粘贴为 vMix 或 OBS 浏览器源 URL 的 Player URL（https://play.screenrig.ai/player/#screen=…）；浏览器源不保留存储，否则每次加载都会丢失配对。Player 每次加载都从该 URL 运行：URL 就是全部配对。再次创建链接会替换它（data.replaced 为 true）：旧 URL 立即失效，从它打开的 Player 会显示无内容的通知。URL 是打开屏幕的凭据：它在敏感标签下打印，不进入操作日志，并可由 screen link show 再次显示。请只在一处打开它。尚未配对的屏幕返回 resource_conflict（退出码 5），已归档的屏幕返回 screen_archived。请求被中断后，重新运行相同命令：它会复用已保存的幂等键，并返回相同的链接。

打印屏幕的链接及其 Player URL。

screen link show <id>

screenrig screen link show scr_01EXAMPLESCREEN00000000

在敏感标签下打印 data.url，并附带 data.hint（密钥的最后四个字符），以及 Player 打开链接后的 data.created_at 和 data.last_used_at。只读凭据收到的 url 为空且 url_redacted 为 true，人工输出会说明 URL 已被保留；Manage 登录则可收到。没有链接的屏幕返回 screen_link_not_found（退出码 4），并给出创建链接的命令。screen show 对有链接的屏幕打印 Screen link: on (…HINT)，绝不打印其 URL。

关闭屏幕的链接。

screen link delete <id> [--expect-rev REVISION]

screenrig screen link delete scr_01EXAMPLESCREEN00000000

URL 立即失效，它打开的每个会话都会结束：仍显示它的浏览器源只会显示通知而无内容，直到获得新的 URL。屏幕、其配对和内容不受影响。屏幕没有链接时，操作成功且不更改任何内容。

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

screen reload (<id>... | --tag TAG) [--expires-in DURATION] [--expect-rev REVISION]

screenrig screen reload scr_01EXAMPLESCREEN00000000
screenrig screen reload scr_01EXAMPLESCREEN00000000 --expires-in 2h
screenrig screen reload --tag Lobby

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

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

screen toast (<id>... | --tag TAG) --text TEXT [--level info] [--duration-ms MS]

screenrig screen toast scr_01EXAMPLESCREEN00000000 --text "Lobby closed"
screenrig screen toast --tag Lobby --text "Closing in ten minutes"

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

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

screen identify <id> [--duration DURATION]

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 screenshot <id> [--output FILE] [--timeout MS] [--poll-ms MS]
screen screenshot (<id> <id>... | --tag TAG) [--output DIRECTORY] [--concurrency N] [--timeout MS] [--poll-ms MS]

screenrig screen screenshot scr_01EXAMPLESCREEN00000000 --output ./lobby.webp

screenrig screen screenshot --tag Lobby --output ./lobby-shots

命令会阻塞直到 WebP 写入磁盘；无 --no-wait。信封报告 screen_id、capture_id、path、bytes、sha256、width 和 height，且从不包含图像字节。最新的请求优先：后续请求会替换正在进行的捕获。 Web 播放器的截图会把每个 iframe 页面绘制为标有“Embedded web page”的深灰色方块，把每个应用绘制为其自身渲染的样子；图像中没有该方块的标记，因此不能证明 iframe 页面已渲染。

针对多个 ID 或 --tag，答案是包含 action: "screenshot"、selector 和 output 目录的 设备组结果；每个 ok 结果包含 path、bytes、sha256、width 和 height。使用 --tag 时，CLI 首先列出带标签的屏幕，跟随每个列表页；每页列表计费，截图免费，多个 ID 无需列表。--idempotency-key 形式被拒绝，因为每个截图使用独立密钥。若截图意外失败，该屏幕结果为 unexpected_error，不启动新截图，仍等待的屏幕报告 not_attempted，退出码为 1。

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

screen tag (<id>... | --tag TAG) (--set TAGS | --add TAGS | --remove TAGS | --clear) [--expect-rev REVISION]

screenrig screen tag scr_01EXAMPLESCREEN00000000 --set Lobby,Floor2
screenrig screen tag scr_01EXAMPLESCREEN00000000 --add Spring
screenrig screen tag --tag Lobby --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 schedule show <id>

screenrig screen schedule show scr_CAFE

JSON 输出可直接返回至 screen schedule set --file。

替换屏幕或车队上的播放列表排程。

screen schedule set (<id>... | --tag TAG) --file FILE [--expect-rev REVISION] [--note TEXT]

screenrig screen schedule set scr_CAFE --file dayparts.json
screenrig screen schedule set --tag Cafe --file dayparts.json

每个计划命名的播放列表都作为分配进行验证，屏幕需要时区和分配的默认播放列表。没有条目生效时，播放分配的播放列表。如果计划播放列表之后无法显示，则跳过其条目并记录screen.playlist_unavailable。

从屏幕或设备组移除播放列表排程。

screen schedule clear (<id>... | --tag TAG) [--expect-rev REVISION] [--note TEXT]

screenrig screen schedule clear --tag Cafe

显示替换屏幕播放列表排程会带来哪些变化，但不执行。

screen schedule preview <id> --file FILE [--calendar-from INSTANT] [--calendar-to INSTANT]

screenrig screen schedule preview scr_LOBBY --file dayparts.json
screenrig screen schedule preview scr_LOBBY --file dayparts.json --calendar-from 2026-12-01T00:00:00Z --calendar-to 2027-01-01T00:00:00Z

不会写入任何内容。条目的检查方式与 screen schedule set 相同，因此预览会拒绝 set 所拒绝的内容。data.gained 和 data.lost 说明屏幕会获得还是失去其排程的层级；带有 "paused": true 的条目不在任何屏幕上，因此发布它会增加该条目。data.calendar.before 和 data.calendar.after 是屏幕现状的日历，以及 --calendar-from 至 --calendar-to 之间更改后的日历。

按从新到旧列出屏幕播放列表排程的修订。

screen schedule revisions <id> [--after CURSOR]

screenrig screen schedule revisions scr_LOBBY
screenrig screen schedule revisions scr_LOBBY --after CURSOR

data.items 最多包含 50 个修订，每个包含 revision（写入时屏幕的修订号，因此屏幕以其他方式变化处的编号有间隔）、created_at、change、current、已知时的 author，以及 entries（该次写入后的完整排程；none 表示屏幕没有排程）。change 为 edited（一次 set、一次 clear 或一次排程导入）、restored（restored_from 所指较早修订的副本）或 baseline。只要 data.next_cursor 是字符串，就还有更早的修订：将 --after 设为该值，再次运行命令。修订随屏幕清除而删除。只读权限即可。

通过向前复制，把较早修订的排程放回屏幕。

screen schedule restore <id> --revision N [--expect-rev REVISION] [--note TEXT]

screenrig screen schedule restore scr_LOBBY --revision 4
screenrig screen schedule restore scr_LOBBY --revision 4 --expect-rev 9

修订 N 的条目成为屏幕的排程，这与用这些条目执行 screen schedule set（若该修订没有条目则为 screen schedule clear）是同一次写入，按现在的规则检查：此后被删除的播放列表会导致拒绝。在 Propose 权限下，或在要求审核代理更改的项目中，恢复会像 set 一样等待有人批准，批准前屏幕上不会有任何变化。较早的修订保持原样。

在屏幕或屏幕组上提前显示一个播放列表，优先于活动、计划和分配。

screen takeover [set] (<id>... | --tag TAG) --playlist-id ID [--until TIME | --for DURATION] [--reason TEXT] [--expect-rev REVISION] [--note TEXT]

screenrig screen takeover scr_LOBBY --playlist-id pl_DRILL --for 30m --reason "Fire drill"
screenrig screen takeover --tag Lobby --playlist-id pl_LAUNCH --for 2h
screenrig screen takeover scr_A scr_B --playlist-id pl_NOTICE --until none

screen takeover ID 是 screen takeover set ID 的缩写。新的接管会替换之前的接管。结束时，屏幕会自动返回生效的活动、其计划或分配的播放列表。无法显示播放列表的接管会结束。模糊失败后的 --for 重跑会重新计算结束时间，并作为新请求发送。

结束屏幕或设备群的接管。

screen takeover clear (<id>... | --tag TAG) [--expect-rev REVISION] [--note TEXT]

screenrig screen takeover clear --tag Lobby

按屏幕读取的顺序列出项目的活动。

campaign list

无参数。

screenrig campaign list

data.items 最多包含 100 个活动，优先级最高的在前，同一优先级内最新的在前。已暂停的活动会被列出，且不适用于任何屏幕。

读取一个活动。

campaign show <id>

screenrig campaign show cmp_LUNCH

返回 name、playlist_id、audience（确切规则）、priority、paused、已设置的 from、until、windows、monthly、dates、except、interaction、displays 和 start，以及 revision，即后续写入时用于 --expect-rev 的值。reach 报告受众匹配多少个屏幕：published 是活动上次发布时的数量（创建时，或更新了新的受众、播放列表或暂停状态时），current 和 at 是最新数量，empty_groups 是受众中不匹配任何屏幕的 tag:NAME 和 folder:ID 叶子节点。更改数量的标签、文件夹、归档或删除操作会在约 15 秒内重新计数；campaign list 也携带 reach，并且 reach_dropped 和 group_empty 通知会监视它。来自 ads campaigns list 的 ID 在此返回 not_found（退出码 4）。

将受众的屏幕切换到一个播放列表，始终切换，或在其规则生效期间切换。

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] [--on-touch [IDLE_S]] [--displays N[,N]] [--start on-time|next-item] [--covers WHERE] [--priority N] [--paused]

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

标签由 1 到 32 个字母或数字组成。DAYS 为 daily、一天（mon）、一个范围（mon-fri；fri-mon 回绕越过一周的末尾）或逗号列表（sat,sun）。不带时间时，时间窗口为全天；结束时间等于或早于开始时间时，该窗口跨越午夜并属于开始日。在 --audience 规则中，每个成员恰好有 all、any、tag、screen_id 或 folder 之一，分组最多嵌套 3 层，一个受众最多有 500 条规则，{"all":[]} 表示每个屏幕。

中断或模糊创建后，24 小时内重新运行相同命令：它会重用保存的幂等键，服务器返回相同活动而非创建新活动。

更改活动；其旧受众和新受众的屏幕会在一分钟内重新解析。

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] [--on-touch [IDLE_S] | --clear-on-touch] [--displays N[,N] | --clear-displays] [--start WHEN] [--covers WHERE] [--priority N] [--expect-rev REVISION]

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

至少传入一项更改；只有传入的字段会更改。新的 --playlist-id 的检查方式与创建时相同。中断或模糊请求后，重新运行相同命令：它会重用保存的幂等键，服务器返回已发生的更新而非再次应用。

在每个屏幕上停止活动，但不删除它。

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

screenrig campaign pause cmp_LUNCH

此前显示它的屏幕会在一分钟内回到没有它时会显示的内容。campaign resume 会重新启动它。

重新启动已暂停的活动。

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

screenrig campaign resume cmp_LUNCH

活动生效期间，受众中活动可适用的每个屏幕会在一分钟内切换到该活动的播放列表。

删除活动。

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

screenrig campaign delete cmp_LUNCH

活动无法恢复。显示它的每个屏幕会在一分钟内回到没有它时会显示的内容；播放列表、屏幕和标签保持不变。campaign pause 会停止活动并保留它。

显示活动覆盖的屏幕及各屏幕的状态。

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