命令参考（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 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

在项目绑定到你账户中的 Rive 文件之前，--publish 会写出带水印的构建。

绑定会把 push.fileId 记录到 rive.yaml 中，由即将推出的 rive push 完成。无论项目是否包含脚本，水印都会生效。

修饰符

这些标志会附加到你选择的模式上。

标志	作用
--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>	将场景向前步进。可重复，并按与其他交互相同的顺序运行
--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>	启动时显示的画板。未知名称会回退到第一个画板，且不发出警告

交互按你写下的顺序运行，--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 下的整帧数，并把手势内部推进的帧也计算在内。

模拟指针

--pointer 接受种类和位置。down、up、move 和 click 各自接受一个点。click 会展开为一次移动、一次按下和一次释放，每步之间隔一帧，因为状态机只在下一次运行时才会看到手势：

rive myproject --screenshot=out.png --pointer=click@120,60

--pointer 只检查值的形状。不是 down、up、move、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 报告对象

预览窗口命令

预览窗口打开时，在终端输入这些命令。

按键	作用
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 自身的名称。目录必须为空或全新。

schema

rive schema <Type>          # 某类型的属性，含继承而来的
rive schema --search <text> # 按名称查找类型或属性，然后选一个

标志	作用
--list	选择要描述的类型。无法绘制选择器时，打印每个类型名
--animatable	只显示可打关键帧的属性
--bindable	只显示可数据绑定的属性
--all	包含仅编辑器使用的属性

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 输出（默认）
--all	包含仅编辑器使用的属性
--artboard=<name>	只输出一个画板。未知名称会给出空的 artboards 列表，仍以 0 退出

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 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	无法连接某项服务，因此可以安全重试

⚠️

退出码 2 不覆盖拼错的标志。在 rive <project-dir> 上，CLI 无法识别的标志会被忽略，因此 --bogus 仍会构建并以 0 退出。值会被检查：--viewport=abc 会以 2 退出并给出消息，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 字符串，行号同样从零开始；位于第一行的问题会完全去掉 :line。--verify 以及任何失败的构建上，data.riv 为 null。日志留在 stderr，因此 stdout 不会夹杂其他内容。

⚠️

--format=json 中的 line 和 column 从零开始，而终端日志和 rive inspect 对同一问题报告从一开始的行号。展示给人员之前请加 1。

环境变量

变量	覆盖内容
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 会回退为打印列表。