命令参考（Commands）
rive COMMAND
在终端运行 rive --help 查看此列表，运行 rive --version 打印已安装版本。
命令
| 命令 | 作用 |
|---|---|
rive create | 在本地搭建 Rive 项目脚手架。会创建：rive.yaml、scene.rml、AGENTS.md、.gitignore |
rive <project-dir> | 打开预览窗口，并在你编辑时重建。目录默认为 . |
rive login | 使用 Rive 账户登录 |
rive logout | 退出登录 |
rive whoami | 显示当前登录身份 |
rive docs | CLI 自带的创作文档 |
rive samples | 把可运行的示例项目克隆到本机 |
rive schema | 查阅类型 |
rive inspect | 打印解析后的场景 |
rive push | 构建项目并上传到账户中的 Rive 文件。需要 rive login |
rive pull | 用关联的 Rive 文件覆盖本地项目。需要 rive login |
rive doctor | 检查环境：版本、鉴权、端口、项目 |
rive lsp | 通过 stdio 提供语言服务器，用于编辑器集成 |
rive update | 安装最新发布的 CLI |
rive switch | 选择一个 CLI 版本，或按名称选中 |
rive uninstall | 移除已缓存的 CLI 版本 |
rive analytics | 查看或设置用量分析（on | off） |
update、switch和uninstall仅支持~/.rive/bin下的安装器构建。若通过 Homebrew 安装 CLI，请使用brew方法管理 CLI 版本与更新。
项目标志
这些标志适用于 rive <project-dir>。
构建模式
互斥，因此只能选一个。捕获（Capture） 下的 --screenshot 也算其中一种。若不指定任何模式，CLI 会打开预览窗口并在你编辑时重建。
| 标志 | 作用 |
|---|---|
--verify | 检查项目但不写出 .riv。出错时退出码为 1 |
--once | 写出未签名的 .riv。出错时退出码为 1 |
--publish | 写出已签名的 .riv。需要 rive login，并且可能给输出加水印，见下方说明。出错时退出码为 1 |
--test | 运行 Tests 脚本。失败时退出码为 6 |
--publish可能会给图形加水印。干净的.riv需要两件事：项目已绑定到你 Rive 账户中的文件，且该文件位于 Cadet 或更高套餐 的工作区中。绑定由rive push完成，它会把push.fileId记录到rive.yaml。无论项目是否包含脚本，水印都会生效。
修饰符
这些标志会附加到你选择的模式上。
| 标志 | 作用 |
|---|---|
--init | 若缺少 rive.yaml 则写入一份，然后继续 |
--rev=<path> | 同时写出编辑器 .rev。需要 rive login。可与 --once 或 --publish 组合；单独使用时也会做一次 --once 构建。不能与 --verify、--test 和 --screenshot 一起使用 |
捕获
| 标志 | 作用 |
|---|---|
--screenshot[=<path>] | 构建、在不打开窗口的情况下渲染一帧、写出 PNG。默认为 build/<name>.png |
--viewport=<WxH> | 场景布局所用的尺寸：配合 --screenshot 时为捕获尺寸，监视时为窗口尺寸。默认为画板自身尺寸 |
--bench=<frames> | 构建、在不打开窗口的情况下为指定帧数计时，报告推进与渲染统计以及 WASM 内存增长 |
--bench 会代替 --screenshot 运行，而不是与它并行。同时传入两者会为帧计时且不写出 PNG，且不会提示。它本身就是一种构建模式，因此不能与 --verify、--once、--publish 或 --test 组合。它按画板自身尺寸渲染并忽略 --viewport，并在计时前先运行 300 帧预热。
驱动场景
| 标志 | 作用 |
|---|---|
--data=<path=value> | 在场景运行前设置一个视图模型属性。重复该标志可设置多个属性 |
--pointer=<kind@x,y> | 在画板坐标处模拟一次指针事件。可重复 |
--advance=<N|Ns|Nms> | 将场景向前步进。可重复，并按与其他交互相同的顺序运行 |
--key=<key[:phase][+mods]> | 模拟一次按键。可重复，并按与其他交互相同的顺序运行 |
--data-dump[=<path>] | 把绑定的视图模型值、全局量和嵌套画板写成 JSON。默认为 build/<name>.data.json；- 或 stdout 写到标准输出 |
--data-dump-filter=<paths> | 只保留这些属性路径，逗号分隔。允许 glob，例如 battery/*,score |
--data-dump-every=<N|Ns|Nms> | 每隔 N 帧采样一次，而不是只在结束时采样一次，格式为 JSON Lines |
--artboard=<name> | 启动时显示的画板。未知名称会回退到第一个画板，且不发出警告 |
--fit=<mode> | 画板映射到视图的方式：fill、contain、cover、fit-width、fit-height、none、scale-down，或默认的 layout |
交互按你写下的顺序运行，--pointer 和 --advance 需要 --screenshot。
推进时间
--advance 会在其他交互之间步进场景。裸数字表示 60fps 下的整帧数；1s 或 250ms 是动画时间，按 1/60s 的帧步进，余数用一帧较短的帧补齐。时间形式支持小数点，因此 1.5s 是 90 帧。
rive myproject --screenshot=out.png --advance=60 # 60 帧
rive myproject --screenshot=out.png --advance=1s # 同样的时长，用时间写法
rive myproject --screenshot=out.png --advance=250ms
按需求放置它：
| 位置 | 作用 |
|---|---|
| 手势之前 | 在交互落地前播放开场 |
| 两次手势之间 | 让一次动作的过渡在下一次开始前完成 |
| 最后一次手势之后 | 在捕获前让场景稳定下来 |
rive myproject --screenshot=out.png \
--advance=1s \
--pointer=click@120,60 \
--advance=20
带符号、空白、尾随文本、裸帧数上的小数点，或超过 32 位无符号整数的值会被拒绝，退出码为 2。
--advance取代了--frame。裸的--advance=N就是以前--frame=N的含义，因此--frame=20应写成--advance=20。传入--frame会报错并提示使用--advance。
--bench使用自己的帧数，不能与--advance、--pointer、--gamepad、--semantics或--semantic-action组合。
设置数据
--data 接受属性路径和值。路径从绑定到画板的视图模型实例开始，每一段都是属性名，因此扁平视图模型用裸属性名，嵌套的则用路径：
rive myproject --screenshot=out.png --data=level=100
rive myproject --screenshot=out.png --data=battery/level=100
每个 --data 设置一个属性。重复该标志可设置多个：
rive myproject --screenshot=out.png \
--data=settings/speed=42 \
--data=settings/scale=9
匹配不到任何属性的路径会记录
data: no property at "<path>"并被丢弃。构建仍然会成功，场景会按该属性的作者设定值渲染。在--quiet下你什么也看不到，因此请确认值确实落地，而不要假定它们生效了。
读回数据
--data 负责写入；--data-dump 负责读回。它会构建、无头运行，并把绑定的视图模型值写成 JSON，以便测试可以断言场景计算出的结果：
rive myproject --data-dump=- --advance=60
--data-dump-every 会把它变成时间序列，而不是单次读数：一个文件头、一帧 0 的基线，然后只输出每次采样中发生变化的内容。它接受 60fps 下的整帧数，并把手势内部推进的帧也计算在内。
模拟按键
--key 会沿真实按键相同的分发路径发送一次按键。阶段为 down、repeat 或 up，默认为 press，即一次 down 再一次 up。修饰键用 + 附加：
rive myproject --screenshot=out.png --key=right
rive myproject --screenshot=out.png --key=a:down
rive myproject --screenshot=out.png --key=tab:down+shift
按键名称与标记语言使用的相同，因此 right、escape、f1 和 kpEnter 都能解析。
按键只会到达当前持有 Rive 焦点的对象。没有焦点时，CLI 会说明这一点，并指出修复方式：文件需要在监听器目标上有
FocusData，以及某种使其获得焦点的手段。
模拟指针
--pointer 接受种类和位置。down、up、move、exit 和 click 各自接受一个点。click 会展开为一次移动、一次按下和一次释放，每步之间隔一帧，因为状态机只在下一次运行时才会看到手势：
rive myproject --screenshot=out.png --pointer=click@120,60
--pointer 只检查值的形状。不是 down、up、move、exit、click 或 drag 的种类也能解析通过，然后在投递时以 pointer: unknown gesture 失败，并以 1 退出。
drag 是第五种，也是唯一形状不同的一种：drag@x1,y1>x2,y2[:steps]。它移动到第一个点、按下、沿线段向第二个点发出 steps 次移动，然后释放。steps 默认为 8。每个事件占用自己的一帧，因此一次拖拽会运行 steps + 3 帧：计数越大，扫过越细越慢；越小则越像轻扫。滚动物理会读取由此隐含的速度，因此计数会改变滚动甩出的距离。
rive myproject --screenshot=out.png --pointer='drag@200,300>200,80:12'
请给
drag的值加上引号，以免 shell 把>当成重定向。
服务
| 标志 | 作用 |
|---|---|
--serve[=port] | 同时把构建推送到已连接的播放器。默认端口 9640 |
--headless-serve | 无本地窗口地提供服务。端口取自 --serve=<port> |
其他
| 标志 | 作用 |
|---|---|
--quiet | 完全没有终端日志，包括编译器错误。请改看退出码、--format=json 或 logs.problems |
--optimize | 以 Luau O2 而不是 O1 编译脚本。脚本运行更快，字节码更难调试 |
--immediate | 在主线程上渲染 |
--format=json 或 --format=human | human 是默认终端日志。json 需要 --once、--verify、--publish 或 --test，并在 stdout 打印一个 JSON 报告对象。--json 是 --format=json 的别名 |
预览窗口命令
预览窗口打开时，在终端输入这些命令。
| 按键 | 作用 |
|---|---|
s 或 screenshot [path] | 写出窗口的 PNG |
p 或 pause | 切换播放 |
a 或 artboard [name] | 切换显示的画板 |
f 或 fit [mode] | 切换画板映射到窗口的方式。单独的 f 会列出模式 |
z 或 size | 把窗口调整到画板大小，并在手动拖拽后再次跟随 |
rev [path] | 写出编辑器 .rev。需要 rive login |
? 或 help | 列出命令 |
各命令标志
create
rive create # 提示输入名称，然后写入该目录
rive create <dir> # 在 <dir> 中写入项目（`.` 是当前工作目录）
rive create [dir] --from-rev=<file.rev>
--from-rev 把编辑器 .rev 转换成项目：scene.rml 加上作为文件的脚本和资源。没有 <dir> 时使用 .rev 自身的名称。目录必须为空或全新。
--from-remote-file 对从 Rive 账户下载的文件做同样的转换。不指定文件 ID 时，CLI 会列出你的项目和文件供你选择。rive.yaml 会记录该链接，因此 rive push 会更新源文件，rive pull 会把远程改动拉回来。这需要先用 rive login 登录。
rive create myproject --from-remote-file # 从列表中选择
rive create myproject --from-remote-file=512 # 或直接指定 file id
schema
rive schema <Type> # 某类型的属性，含继承而来的
rive schema --search <text> # 按名称查找类型或属性，然后选一个
| 标志 | 作用 |
|---|---|
--list | 选择要描述的类型。无法绘制选择器时，打印每个类型名 |
--animatable | 只显示可打关键帧的属性 |
--bindable | 只显示可数据绑定的属性 |
--all | 包含仅编辑器使用的属性 |
--json | JSON 输出：类型作为一个对象，或 --list / --search 结果作为一个数组 |
docs
rive docs # 文档索引
rive docs <topic> # 一个主题，例如 `layout` 或 `luau/protocols`
| 标志 | 作用 |
|---|---|
--list | 选择要阅读的主题 |
--search <text> | 在所有主题中匹配文本的行 |
--path | 打印磁盘上的文档目录 |
samples
rive samples # 选一个并复制到新目录
rive samples --path # 打印磁盘上的示例目录
inspect
rive inspect [dir] # 解析后的场景，以 JSON 输出。目录默认为 `.`
当 problems 包含错误时退出 1；目录没有 rive.yaml 时在 stderr 打印消息并以 1 退出。
| 标志 | 作用 |
|---|---|
--json | JSON 输出（默认） |
--summary | 问题，以及按类型、按画板和其他根对象的对象计数。不是整棵树 |
--all | 包含仅编辑器使用的属性 |
--artboard=<name> | 只输出一个画板。未知名称会给出空的 artboards 列表，仍以 0 退出 |
push
rive push [dir] # 构建项目并发送到已绑定的 Rive 文件
这会把项目上传到你的 Rive 账户，替换已绑定文件的内容，并在其修订历史中添加一条记录。产物与 --rev 导出的相同。
| 标志 | 作用 |
|---|---|
--project=<id> | 第一次 push 使用的项目。回退到 rive.yaml 中的 push.projectId；只有一个项目时会自动选中，多个则会打开选择器 |
--list | 列出你的项目及其 id，然后退出 |
--name=<label> | 修订历史标签。默认为 rive-cli push |
--optimize | 以 O2 编译脚本 |
--quiet | 抑制构建日志 |
参见推送到 Rive 文件。
pull
rive pull [dir] # 用已绑定的 Rive 文件覆盖本地项目
下载项目所绑定的 Rive 文件，并写入本地项目：场景标记，以及每个脚本、着色器和资源文件。字节已经一致的文件会保持不动；远程文件中缺失的构建输入会报告出来，而不是被删除。
rive.yaml 会采用远程文件的主画板和构建设置，并保留其余每一行。AGENTS.md、CLAUDE.md 以及你另外加入的内容都不会被改动。
| 标志 | 作用 |
|---|---|
--yes | 跳过确认。CI 以及没有终端可供询问的环境必须使用 |
--quiet | 只报告发生了什么变化 |
该命令会点出文件和项目，并在运行前询问，默认是否：
Pulling file 2603061 overwrites /path/to/myproject's scene, scripts and assets with the remote file's.
Overwrite local changes? [y/N]:
目前，pull 会用远程文件替换本地项目的场景、脚本和资源。
doctor
rive doctor [project-dir]
| 标志 | 作用 |
|---|---|
--format=json | 在 stdout 输出机器可读报告 |
doctor 打印五项检查（version、update、auth、live-link 和 project），每项为 ok、warn 或 fail。全部为 ok 或 warn 时退出 0，有检查失败时退出 1。
登录
| 你运行的内容 | 是否需要会话 |
|---|---|
--publish、--rev、rive push、rive pull、create --from-remote-file | 是，通过 rive login |
预览窗口、--once、--verify、--test、--screenshot、--serve、--headless-serve | 否，并且这些操作可离线使用 |
create、docs、samples、schema、inspect | 否 |
update、whoami、doctor | 不需要账户，但会访问网络。whoami 未登录时退出 3，无法连接 Rive 时退出 7；doctor 把缺失会话报告为警告并仍退出 0，但有检查失败时退出 1 |
凭据存放在项目之外：macOS 和 Linux 上为 ~/.config/rive/app.rive.cli/，并遵循 XDG_CONFIG_HOME；Windows 上为 Windows Credential Manager。
受门控的模式会实时检查会话，因此即使本地存有有效凭据，连接中断时
--publish和--rev也会失败。
退出码
| 代码 | 含义 |
|---|---|
0 | 成功 |
1 | 构建错误，或没有更具体代码的任意失败 |
2 | CLI 解析后拒绝的标志：错误的 --pointer、--data、--advance 或 --viewport 值；已移除的 --frame；--format 给出了除 json 或 human 以外的值；没有构建模式却使用 --format=json；同时指定两种构建模式；在不写出任何内容的模式下使用 --rev；没有 --screenshot 的交互；或在项目外运行不带参数的 rive |
3 | 未登录，或会话被拒绝 |
6 | 测试用例失败。构建本身没问题 |
7 | 无法连接某项服务，因此可以安全重试 |
任何不以
--开头的参数都会被当成项目目录。传入多个不算错误：CLI 会构建最右侧的那个，且不会提及其他参数，因此多余的单词会改变构建对象。
JSON 输出
在 --once、--verify、--publish 或 --test 上使用 --format=json 会在 stdout 打印一个 JSON 对象。data 因模式而异。--verify 和 --once 携带构建信息：
{"success": true, "command": "build", "data": {"riv": "./build/myproject.riv", "bytes": 140, "buildMs": 2.0, "problems": []}, "errors": [], "warnings": []}
--test 携带运行结果：
{"success": false, "command": "test", "data": {"passed": 5, "failed": 1, "noTestsFound": false, "failures": [{"test": "clamp > intentional failure", "line": 29, "message": "5 is not equal to 10"}]}, "errors": ["clamp > intentional failure: 5 is not equal to 10"], "warnings": []}
command 是模式名，而不是标志：--once 为 "build"，--verify 为 "verify"，--publish 为 "publish"，--test 为 "test"。data.problems 中的每一项是 {severity, kind, code, script, line, column, message}，其中 severity 为 error、warning 或 hint。errors 把它们重复为 script:line message 字符串。--verify 以及任何失败的构建上，data.riv 为 null。日志留在 stderr，因此 stdout 不会夹杂其他内容。
环境变量
| 变量 | 覆盖内容 |
|---|---|
RIVE_API_BASE | API 主机。自定义主机也会有自己的已存储登录 |
RIVE_NO_TUI | 除 0 以外的任何值都会禁用交互式选择器 |
TERM | 未设置、为空或 dumb 会禁用交互式选择器 |
NO_COLOR | 绘制无颜色的选择器 |
RIVE_HOME | CLI 的安装与状态根目录。默认为 ~/.rive |
XDG_CONFIG_HOME | 在 macOS 和 Linux 上重定位凭据目录 |
RIVE_DOCS_DIR | rive docs 读取的目录 |
RIVE_SAMPLES_DIR | rive samples 复制来源的目录 |
RIVE_ANALYTICS | 强制分析同意：on/1/true/yes，或 off/0/false/no |
交互式选择器画在 stderr 上，因此只重定向 stdout 并不会禁用它们。无法绘制选择器时（
TERM=dumb、RIVE_NO_TUI=1，或 stdin 不是终端，例如 CI），CLI 会回退为打印列表。