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