# Cavalry CLI

### 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/Applications/CavalryCLI.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
  auth                        Authenticate (Password may be piped or entered when prompted)
  proxy                       Set proxy settings
  list                        List additional information
```

###

### Render

{% hint style="warning" %}
Rendering via CLI is only available on the **Professional** plan.
{% endhint %}

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
```

{% hint style="info" %}
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](https://scenegroup.gitbook.io/cavalry/user-interface/menus/window-menu/asset-window/project-settings).
{% endhint %}

#### Render Tokens

To use Render Tokens to generate a **File Name** (`-n`) with in 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 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
```

###

### **Auth**

You'll need to authenticate in order to use CLI to render. If you have used the main Cavalry application with a Professional licence recently then you will already be authenticated but in the event that you haven't, you can use the `auth` command to do so.

Typing `./cavalry-cli auth -h` (macOS) or `.\cavalry-cli auth -h` (Windows) followed by enter 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
```

For example, the below will sign in using your email address (the one you use to sign in to Cavalry):

```
./cavalry-cli auth name@email.com
```

You will then be asked to enter your password.

Once authenticated, any Render commands will run .

### Proxy

[Proxy Server](https://scenegroup.gitbook.io/cavalry/getting-started/sign-in/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 enter 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

{% hint style="warning" %}
Only available on the **Professional** plan.
{% endhint %}

You can 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.

### **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`