Cavalry CLI

Command Line Interface

General

Cavalry CLI (Command Line Interface) enables various tasks including rendering without the need to launch Cavalry itself.

To run (assuming you have installed Cavalry to the default locations):

macOS

  • Open Terminal (Applications/Utilities/Terminal).

  • Enter the following (hit enter after the first line).

$ cd /Applications/Cavalry.app/Contents/MacOS
$ ./cavalry-cli [your command here]

Windows

  • Open Command Prompt.

  • Enter the following (hit enter after the first line)

> cd C:\Program Files\Cavalry
> .\cavalry-cli [your command here]

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

Command Line Interface
Usage: Cavalry CLI [OPTIONS] [SUBCOMMAND]
-h,--help Print this help message and exit
Subcommands:
render Render a scene
version Version information
list List additional information

Render

Typing ./cavalry-cli render -h (macOS) or .\cavalry-cli render -h (Windows) followed by enter 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].
[format]
Rendering format
--format TEXT Sets the output format. Options: png (default), jpeg, svg, gif, apng, prores
[PNG]
--compression INT Compression (0 to 9)
--filter INT Filter (1, 2 or 3)
[JPEG]
--quality INT Quality (0 to 100)
[ProRes]
--codec TEXT 422HQ, 422, 422LT, 422Proxy, 4444, 4444XQ

You can then use these flags to create your command.

For example, the below will render frames 0-50 of the file sceneName.cv as an animated png with the name outputFileName to your 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

If your file was saved with a Project set, if you don't set a -d (directory) any output will be saved in the Renders directory defined in the Project Settings.

List

You can also list additional information about your scene like the Composition and Render Queue item Ids. These can be added to the render command as flags. Typing ./cavalry-cli list -h (macOS) or .\cavalry-cli list -h (Windows) followed by enter 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 enter will return a list of the compositions in your 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, if you wanted to render Composition 1 you would add --composition compNode#1 to the render command.

Version

To check the version of Cavalry you currently have installed you can 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

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 float is 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