Skip to main content

Cavalry CLI

General​

Cavalry CLI (Command Line Interface) enables various tasks including rendering without the need to launch Cavalry's UI. Certain features are only available with an Enterprise licence.

StarterProfessionalEnterprise
render✔️
list✔️
--prompt✔️
version✔️✔️✔️
auth✔️✔️✔️
proxy✔️✔️✔️

Get Started​

To run the CLI (assuming Cavalry is installed to the default locations):

macOS

  • Open Terminal (Applications/Utilities/Terminal).
  • Enter the following command to change directory (cd). 
    cd /Applications/Cavalry.app/Contents/Applications/CavalryCLI.app/Contents/MacOS/
  • Hit Return then type: 
    ./cavalry-cli [your command here]

Windows

  • Open Command Prompt.
  • Enter the following command to change directory (cd). 
    cd C:\Program Files\Cavalry
  • Hit Return then type: 
    .\cavalry-cli [your command here]

Typing ./cavalry-cli -h (macOS) or .\cavalry-cli -h (Windows) followed by Return will output the following help information:

Command Line Interface
Usage: 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 Feature

This feature is only available with an Enterprise licence. Contact us for details.

Typing ./cavalry-cli render -h (macOS) or .\cavalry-cli render -h (Windows) followed by Return will output the following help information:

Render a scene
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.
  --backend TEXT              The rendering backend. Options: opengl (default), raster.
  --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 options will be ignored.
  --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
  [QuickTime]
      --codec TEXT                JPEG, Uncompressed, 422HQ, 422, 422LT, 422Proxy, 4444, 4444XQ
      --quality INT               Quality (0 to 100)
  [MP4]
      --quality INT               Quality (0 to 3)
      --bitrate FLOAT             Bitrate in MB/s
  [Audio]
      --audioQuality INT          AAC bitrate in kbps, e.g 128
      --audioSampleRate INT       Sample Rate in Hz, e.g 48000

These flags can then be used to create the command.

For example, the below will render frames 0-50 of the file sceneName.cv as an animated png with the name outputFileName to the Desktop.

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
Project Settings

If the scene file was saved with a Project set and a -d (directory) is not defined, any output will be saved in the Renders directory defined in the Project Settings.

Asset Swapping

An asset (image, audio, csv, svg etc) can be swapped for another at render time using --assetSwap. Arguments should be entered in pairs:

  • The AssetId
  • The new path or URL

For example --assetSwap asset#2 ~/Desktop/cavalry.jpg.

The Asset ID can be found by right clicking on an Asset in the Assets Window and choosing Copy Asset Id.

Render Tokens​

To use Render Tokens to generate a File Name (-n) within a command wrap them in single or double quotes. For example the following examples will both work:

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

version​

To check the version of Cavalry currently installed, run the version command.

Typing ./cavalry-cli version -h (macOS) or .\cavalry-cli version -h (Windows) will output the following help information.

Version information
Usage: Cavalry CLI version [OPTIONS]

  -h,--help                   Print this help message and exit

macOS

./cavalry-cli version

Windows

.\cavalry-cli version

Will return the version of Cavalry installed.

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

auth​

Authentication is required in order to use the CLI for rendering.

Typing ./cavalry-cli auth -h (macOS) or .\cavalry-cli auth -h (Windows) followed by Return will output the following help information:

Authenticate (Password may be piped or entered when prompted)
Usage: Cavalry CLI auth [OPTIONS] email

  email TEXT REQUIRED         Email Address
./cavalry-cli auth name@email.com

On hitting Return, a password will be requested.

Alternatively, the password can be piped:

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

proxy​

Proxy Server settings can be entered/updated using the proxy command. Typing ./cavalry-cli proxy -h (macOS) or .\cavalry-cli proxy -h (Windows) followed by Return will output the following help information:

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 Feature

This feature is only available with an Enterprise licence. Contact us for details.

Additional information about a scene like the Composition and Render Queue item Ids can be listed. These can be added to the render command as flags. Typing ./cavalry-cli list -h (macOS) or .\cavalry-cli list -h (Windows) followed by Return will output the following help information:

List additional information
Usage: 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

For example, the below will output information about all the compositions in that scene.

macOS

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

Windows

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

Hitting Return will return a list of the Compositions in the scene and their IDs.

[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

The Composition ID can then be used with the --composition flag as part of a render command. For example, to render Composition 1 add --composition compNode#1 to the render command.

--prompt​

Enterprise Feature

This feature is only available with an Enterprise licence. Contact us for details.

The CLI can be used in combination with the JavaScript API by using the --prompt argument. This makes it possible to interact with Cavalry without the UI.

To launch the CLI in interactive JavaScript mode:

macOS

  • Open Terminal (Applications/Utilities/Terminal).
  • Enter the following command to change directory (cd). 
    cd /Applications/Cavalry.app/Contents/Applications/CavalryCLI.app/Contents/MacOS/
  • Hit Return then type: 
    ./cavalry-cli --prompt
  • Hit Return.

Windows

  • Open Command Prompt.
  • Enter the following command to change directory (cd). 
    cd C:\Program Files\Cavalry
  • Hit Return then type: 
    .\cavalry-cli --prompt
  • Hit Return.

It's now possible to enter JavaScript commands. For example:

// 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();

It's also possible to 'pipe' commands by using the | symbol so that more than one can be run. For example:

api.set("basicShape#1", {"material.materialColor": "#6437ff"}) | api.renderAll()
Semi-colons in piped commands

Note that the use of semi-colons (;) to terminate lines can generate errors when piping commands. For example:

This will error (includes semi-colon after the first command):

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

But this will work:

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

Error Codes​

info

The CLI should be run from a process (e.g from JavaScript in Cavalry) to get the return value. Alternatively, if running the CLI directly in Terminal or Command Prompt, the following commands can be used to get the return value of the last executed command:

  • Terminal - echo $?
  • Command Prompt - echo %ERRORLEVEL%
Return ValueError
0Success.
200Sign in failed. It may be that the licence server was unreachable. See console for more details.
201Sign in failed due to empty password field.
202Licence is invalid. Sign in with the --auth command to continue.
203Licence is invalid. An Enterprise licence is required for this feature.
204Could not load the Scene file.
205Render Queue Item does not exist.
206Validate licence error. Could not save a licence file to disk.

Glossary​

INT - An integer is a number without a decimal point. e.g. 4

INT x 2 - A set of two integers to define a range. e.g. 4 8 (4[space]8)

FLOAT - A number that has a decimal place. e.g. 23.5

TEXT - A text string that can include letters, numbers, special characters, the dash symbol, or the number sign. e.g. sceneName-01