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)

これらのフラグを使用してコマンドを構築できます。

例えば、以下のコマンドは sceneName.cv ファイルの 0-50 フレームをアニメーション PNG として、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 インスタンスでは、SSL サーバー検証に CA（認証局）証明書が必要な場合があります。その場合は --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 は --prompt 引数を使用して JavaScript API と組み合わせて使用できます。これにより、UI なしで Cavalry と対話することが可能になります。

CLI をインタラクティブ JavaScript モードで起動するには：

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 から）戻り値を取得する必要があります。または、CLI を Terminal または Command Prompt で直接実行する場合、以下のコマンドで最後に実行したコマンドの戻り値を取得できます：

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

戻り値	エラー
0	成功。
200	サインインに失敗しました。ライセンスサーバーに到達できなかった可能性があります。詳細はコンソールを確認してください。
201	パスワードフィールドが空のため、サインインに失敗しました。
202	ライセンスが無効です。—auth コマンドでサインインして続行してください。
203	ライセンスが無効です。この機能には Enterprise ライセンスが必要です。
204	シーンファイルを読み込めませんでした。
205	レンダーキュー項目が存在しません。
206	ライセンス検証エラー。ライセンスファイルをディスクに保存できませんでした。

用語集

INT - 小数点を含まない整数。例：4

INT x 2 - 範囲を定義する 2 つの整数。例：4 8（4[スペース]8）

FLOAT - 小数位を持つ数値。例：23.5

TEXT - 文字、数字、特殊文字、ダッシュ記号、または番号記号を含むテキスト文字列。例：sceneName-01