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