Cavalry CLI

CLI 目前在 Cavalry 2.7 及以上版本中不可用。

概述

Cavalry CLI（命令行界面）可执行多种任务，包括无需启动 Cavalry UI 即可进行渲染。部分功能仅对 Enterprise 许可证用户开放。

	Starter	Professional	Enterprise
render			✔️
list			✔️
—prompt			✔️
version	✔️	✔️	✔️
auth	✔️	✔️	✔️
proxy	✔️	✔️	✔️

快速入门

要运行 CLI（假设 Cavalry 已安装到默认位置）：

macOS

• 打开 Terminal（Applications/Utilities/Terminal）。

• 输入以下命令切换目录（cd）。

  cd /Applications/Cavalry.app/Contents/Applications/CavalryCLI.app/Contents/MacOS/

• 按 Return 键后输入：

  ./cavalry-cli [your command here]

Windows

• 打开 Command Prompt。

• 输入以下命令切换目录（cd）。

  cd C:\Program Files\Cavalry

• 按 Return 键后输入：

  .\cavalry-cli [your command here]

输入 ./cavalry-cli -h（macOS）或 .\cavalry-cli -h（Windows）并按 Return 键，将输出以下帮助信息：

Command Line InterfaceUsage: Cavalry CLI [OPTIONS] [SUBCOMMAND]  -h,--help                   Print this help message and exit  --prompt                    Enter continuous command-line mode in which JavaScript commands can be executed.Subcommands:  render                      Render a scene. This requires an Enterprise licence.  version                     Version information  auth                        Authenticate (Password may be piped or entered when prompted)  proxy                       Set proxy settings  list                        List additional information. This requires an Enterprise licence.

render

此功能仅对 Enterprise 许可证用户开放。详情请联系我们。

输入 ./cavalry-cli render -h（macOS）或 .\cavalry-cli render -h（Windows）并按 Return 键，将输出以下帮助信息：

Render a scene. This requires an Enterprise licence.Usage: Cavalry CLI render [OPTIONS] scene  scene TEXT REQUIRED         The full path to the Scene file.  -h,--help                   Print this help message and exit  -p,--padding INT            Frame number padding.  -f,--frame INT              A single frame to render. If set, startFrame and endFrame will be ignored.  -s,--startFrame INT         The first frame of a range to render.  -e,--endFrame INT           The last frame of a range to render.  -n,--name TEXT              The filename prefix.  -d,--directory TEXT         The output directory.  --audio BOOLEAN             Export audio with supported video formats.  --backend TEXT              The rendering backend. Options: gpu (default), cpu.  --scale FLOAT               The Resolution Scale (unit: percent).  --composition TEXT          The ID of the composition to render. See the 'list' command for more info.  --render-item TEXT          The ID of the render item to render. See the 'list' command for more info. Note: All other Render Queue Item options will be ignored.  --all-render-items BOOLEAN  Set this to true to render all Render Queue Items.Note: All other Render Queue Item options will be ignored.  --step INT                  Render every 'n'th frame.  --dynamicCount INT          The number of Dynamic Renders to perform.  --dynamicRange INT x 2      Set an inclusive range of Dynamic Renders to perform [start end].  --assetSwap TEXT x 2        Swap the file or URL that an asset points to [assetId path/url].[format]  Rendering format    --format TEXT               Sets the output format. Options: png (default), jpeg, svg, gif, apng, webm, webp, mp4, quicktime, audio  [PNG]      --compression INT           Compression (0 to 9)      --filter INT                Filter (1, 2 or 3)  [JPEG]      --quality INT               Quality (0 to 100)  [WebP]      --quality INT               Quality (0 to 100)  [WebM]      --codec TEXT                VP9, VP8    [Audio... (line truncated to 2000 chars)

这些标志可用于构建命令。

例如，下面的命令将以动画 png 格式渲染文件 sceneName.cv 的第 0-50 帧，输出文件名为 outputFileName，保存到桌面。

macOS

./cavalry-cli render ~/Desktop/sceneName.cv -n outputFilename -d ~/Desktop/ -s 0 -e 50 --format apng

Windows

.\cavalry-cli render C:\Users\Username\Desktop\sceneName.cv -n outputfilename -d C:\Users\Username\Desktop\ -s 0 -e 50 --format apng

如果场景文件保存时已设置了项目，且未定义 -d（目录），则输出将保存到项目设置中定义的 Renders 目录。

可以在渲染时使用 --assetSwap 将资源（图像、音频、csv、svg 等）替换为其他文件。参数应成对输入：

• AssetId
• 新路径或 URL

例如 --assetSwap asset#2 ~/Desktop/cavalry.jpg。

Asset ID 可以通过在资源窗口中右键单击资源并选择 Copy Asset Id 来找到。

渲染令牌

要在命令中使用渲染令牌生成文件名（-n），请用单引号或双引号将其括起来。例如以下两种写法均可正常工作：

-n '<Composition>_Name'-n "Name_<Resolution>"

version

要检查当前安装的 Cavalry 版本，请运行 version 命令。

输入 ./cavalry-cli version -h（macOS）或 .\cavalry-cli version -h（Windows）将输出以下帮助信息。

Version informationUsage: Cavalry CLI version [OPTIONS]  -h,--help                   Print this help message and exit

macOS

./cavalry-cli version

Windows

.\cavalry-cli version

将返回已安装的 Cavalry 版本。

[11:30:29.657 info    ] App Version: 0.15

auth

使用 CLI 进行渲染需要先完成身份验证。

输入 ./cavalry-cli auth -h（macOS）或 .\cavalry-cli auth -h（Windows）并按 Return 键，将输出以下帮助信息：

Authenticate (Password may be piped or entered when prompted)Usage: Cavalry CLI auth [OPTIONS] email  email TEXT REQUIRED         Email Address  -h,--help                   Print this help message and exit  --sslCertificatePath TEXT   Specify the path to a CA (Certificate Authority) certificate (e.g a cacert.pem file)

./cavalry-cli auth name@email.com

按 Return 键后，系统将提示输入密码。

或者，也可以通过管道传入密码：

echo "yourPassword" | sudo ./cavalry-cli auth name@email.com

Docker 实例可能需要 CA（证书颁发机构）证书来进行 SSL 服务器验证。使用 --sslCertificatePath 指定证书路径。

proxy

可以使用 proxy 命令输入/更新代理服务器设置。输入 ./cavalry-cli proxy -h（macOS）或 .\cavalry-cli proxy -h（Windows）并按 Return 键，将输出以下帮助信息：

Set proxy settings [At least 1 of the following options are required]Usage: Cavalry CLI proxy [OPTIONS]  -h,--help                   Print this help message and exit  --address TEXT Excludes: --reset                              Server Address  --username TEXT Needs: --address Excludes: --reset                              Username (Password may be piped or entered when prompted)  --reset Excludes: --address --username                              Reset proxy settings

list

此功能仅对 Enterprise 许可证用户开放。详情请联系我们。

可以列出场景的附加信息，如合成和渲染队列项的 ID。这些可作为标志添加到 render 命令中。输入 ./cavalry-cli list -h（macOS）或 .\cavalry-cli list -h（Windows）并按 Return 键，将输出以下帮助信息：

List additional informationUsage: Cavalry CLI list [OPTIONS] [scene]  scene TEXT                  The full path to the scene file.  -h,--help                   Print this help message and exit  --compositions Needs: scene List all compositions  --render-items Needs: scene List all render items

例如，以下命令将输出该场景中所有合成的相关信息。

macOS

./cavalry-cli list ~/Desktop/sceneName.cv --compositions

Windows

.\cavalry-cli list C:\Users\Username\Desktop\sceneName.cv --compositions

按 Return 键后将返回场景中的合成列表及其 ID。

[11:17:43.468 info    ] Relinked asset: asset#2[11:17:43.471 info    ] Composition ID                Composition Name              [11:17:43.471 info    ] compNode#1                    Composition 1                 [11:17:43.471 info    ] [11:17:43.471 debug   ] Saving preferences

然后可以将 Composition ID 与 --composition 标志一起用于 render 命令。例如，要渲染 Composition 1，请在 render 命令中添加 --composition compNode#1。

—prompt

此功能仅对 Enterprise 许可证用户开放。详情请联系我们。

CLI 可以与 JavaScript API 结合使用，通过 --prompt 参数实现。这样就可以在不启动 UI 的情况下与 Cavalry 进行交互。

要以交互式 JavaScript 模式启动 CLI：

macOS

• 打开 Terminal（Applications/Utilities/Terminal）。

• 输入以下命令切换目录（cd）。

  cd /Applications/Cavalry.app/Contents/Applications/CavalryCLI.app/Contents/MacOS/

• 按 Return 键后输入：

  ./cavalry-cli --prompt

• 按 Return 键。

Windows

• 打开 Command Prompt。

• 输入以下命令切换目录（cd）。

  cd C:\Program Files\Cavalry

• 按 Return 键后输入：

  .\cavalry-cli --prompt

• 按 Return 键。

现在可以输入 JavaScript 命令了。例如：

// Print 'hello' to the console.console.log("hello");// Open a Cavalry Scene.api.openScene("/Path/To/file.cv", true);// Set an attribute within the open Scene.api.set("basicShape#1", {"material.materialColor": "#6437ff"});// Render all RQIs.api.renderAll();

也可以通过 | 符号”管道”传入多个命令，以便一次运行多个命令。例如：

api.set("basicShape#1", {"material.materialColor": "#6437ff"}) | api.renderAll()

请注意，在管道传入命令时，使用分号（;）来终止行可能会导致错误。例如：

这会出错（第一个命令后有分号）：

api.set("basicShape#1", {"material.materialColor": "#6437ff"}); | api.renderAll();

但这可以正常工作：

api.set("basicShape#1", {"material.materialColor": "#6437ff"}) | api.renderAll();

错误码

CLI 应从进程中运行（例如从 Cavalry 中的 JavaScript）以获取返回值。或者，如果直接在 Terminal 或 Command Prompt 中运行 CLI，可以使用以下命令获取最后执行命令的返回值：

• Terminal - echo $?
• Command Prompt - echo %ERRORLEVEL%

返回值	错误
0	成功。
200	登录失败。可能是许可证服务器无法访问。请查看控制台以获取更多详细信息。
201	由于密码字段为空，登录失败。
202	许可证无效。请使用 —auth 命令登录以继续。
203	许可证无效。此功能需要 Enterprise 许可证。
204	无法加载场景文件。
205	渲染队列项不存在。
206	验证许可证错误。无法将许可证文件保存到磁盘。

术语表

INT - 整数是没有小数点的数字。例如 4

INT x 2 - 定义范围的两个整数。例如 4 8（4[空格]8）

FLOAT - 带有小数位的数字。例如 23.5

TEXT - 可以包含字母、数字、特殊字符、短划线或井号的文本字符串。例如 sceneName-01