# 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](/cavalry/user-interface/menus/window-menu/asset-window/project-settings.md). {% 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 '_Name' -n "Name_" ``` ### ### 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](/cavalry/getting-started/sign-in/proxy-server.md) 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` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://scenegroup.gitbook.io/cavalry/applications/cavalry-cli.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.