Command-line Interface (CLI)¶
The Excelsior Editor is fantastic for working visually. You can prepare a model, dress it, render pictures and videos, and publish interactive links, all in real time in your browser. But when the job is a whole catalog of hundreds or thousands of model renders or videos, no amount of clicking scales. You need a power tool. Enter the Excelsior Command-line Interface (CLI).
The Windows version of the (Web) Excelsior Editor, called webex.exe, is a fully scriptable workhorse. Point it at a scene, hand it a script of commands, and it will apply materials, tune properties, and render pictures, videos, spinners, and exports without ever opening a window.
This is industrial-scale rendering: the CLI's natural habitat is the massive, unattended batch. Renew the visuals of your entire website overnight, re-render a whole catalog after a branding change, or generate thousands of material and ambience variations of a design, all from a script that runs while you sleep.
And because it is a stand-alone executable, the CLI slots into any automation you already have: call it from a Python script, wire it into a render farm, generate its command scripts straight from your product database, or let an LLM agent write and drive the scripts for you. Anything that can launch a process and write a text file can run Maverick Excelsior at scale.
Licensing
The CLI is not included in any subscription tier, not even the Viewer SDK tier. It is licensed separately, on a case-by-case basis. If you have a batch project in mind, contact us and we will put together terms that fit it. Licensing the CLI gets you a copy of the CLI plus a CLI-enabled API key: the ak_xxx value that every command on this page passes with -k:.
We can do the heavy lifting for you
Beyond licensing, we offer bespoke CLI services: we can tailor the tooling to your pipeline (your naming conventions, your looks, your output formats), or simply run the whole batch for you. Again, contact us and we will study your needs.
Switches¶
webex.exe -k:<api_key> -i:<scene> -s:"<cmd>;<cmd>;..." [-S:<script_file>] [-o:<output>] [-w]
| Switch | Description | |
|---|---|---|
-k:<api_key> | required | Your CLI-enabled API key (the ak_xxx value you receive when you license the CLI from us). Validated before anything runs. The key is masked in console output. |
-i:<path> | required | Input scene to load: .3dm, .glb, or .webex. |
-s:<script> | required * | Inline script where you describe what commands will run: commands separated by ;. Newlines inside the string are also accepted as separators. |
-S:<path> | required * | Load a script file (one command per line). May be combined with -s; inline commands run first, then the file's. In general, we encourage the use of -S (script files) over -s (inline strings). |
-o:<path> | optional | Output path pattern. A printf style index (e.g., %02d) is replaced with the command number, so one script can emit several files. Any extension you give is replaced by the action's own (.jpg, .mp4, .webex). Omit it and each capture is saved in the working directory under an automatic name, excelsior_cmd_NN_<action> (e.g., excelsior_cmd_02_picture.jpg, excelsior_cmd_02_video.mp4), where NN is the command number. |
-w | optional | Show the render viewport in a window while running. Without it, the run is headless. |
-x | optional | Accepted for compatibility. The application always exits when the script completes, whether or not -x is passed. |
-h, --help, -? | optional | Print usage and exit. |
Every run needs three things
An API key (-k), an input scene (-i), and something to do. The something to do is a script of commands, which you can pass inline on the command line (-s), or load from a script file (-S).
Script syntax¶
- Commands are separated by
;when inline (-s), or one per line in a script file (-S). - Blank lines are ignored. Lines starting with
#are comments. - Only
set_stringunderstands double quotes, for node names containing spaces. - Each command is echoed to the console as
[NN] <command>as it runs; failures are reported with a specific error message.
Command reference¶
Properties¶
| Command | Description |
|---|---|
set <ustr> <value> | Set a node property by its USTR identifier. The prefix picks the target node automatically: globals_, animation_, camera_, or render_pipeline_. See the whole list of Scene properties (USTR). This is the command you would use to affect global settings such as the render resolution. |
set_string <node> <ustr> <value> | Set a node property by its USTR identifier, by giving the explicit name of the node. <node> may be a special alias such as ::camera, or a layer name (quote it if it has spaces). This is the command you would use to reach per-layer obj_* properties. Note that each change in an attribute restarts the render to reflect the new state. |
Triggering void (button) properties
Void (button) properties are triggered rather than set. The value is ignored but must be present. For example, set_string ::camera camera_center_view 1 re-centers the view on the scene (useful, e.g., after hiding layers).
Materials and ambience¶
| Command | Description |
|---|---|
apply_mtl <layer>:<material> | Apply a library material to a layer. Both the layer name and the material name are case-sensitive. See Content library names. |
apply_amb <shelf>:<name> | Apply an ambience preset. The shelf is the lowercase shelf alias (white, black, ...) and the name is the preset id, e.g., Ambience01w. Both are case-sensitive. |
Layers¶
Renaming a geometry layer, reassigning its material family, or toggling its visibility on/off can be scripted with the following commands:
| Command | Description |
|---|---|
set_layer_alias <layer>:<new name> | Rename a layer. A collision with a sibling name auto-increments until unique. Later commands must use the new name. |
set_layer_family <layer>:<family> | Reassign a layer to gemstone, metal, pearl, or plastic. The layer will pick up the new family's default material. |
set_string "<layer>" obj_visible 0 | Hide a layer (or show it with 1). |
Duplicate layer names
Layers are addressed by name; when a file carries duplicate names (typical of .glb exports), the first match wins, so rename the duplicates first. list_layers prints the current names.
Imported models only
Renaming and family reassignment are only available on imported models (.3dm and .glb inputs). Exporting to .webex seals the layer structure: a .webex scene loads with its layers final, ready to dress and render.
Dressings¶
| Command | Description |
|---|---|
export_dressing [categories:]<file> | Export the scene's settings (its "dressing") as a tiny settings-only .webex_dressing (no geometry, no assets). Settings travel in categories that mirror the editor pages: pose, camera, ambience, backplate, globals, video, atlas, viewer, and branding. By default all of them are exported; prefix the path with a comma-separated category list and a colon to export a subset, e.g., export_dressing camera,ambience:hero.webex_dressing. The file records which categories it carries. |
import_dressing [categories:]<file> | Load a dressing file and reproduce its page categories on the current scene, then reset the render. By default everything the file carries is applied; prefix the path with a comma-separated category list and a colon to apply a subset, e.g., import_dressing camera:hero.webex_dressing. Categories absent from the file or from the list are left untouched. |
Discovery¶
| Command | Description |
|---|---|
list_layers | Print every layer name in the loaded scene, grouped by family. |
list_materials | Print every material name in the library. |
list_ambiences | Print every ambience as shelf:name, ready to paste into apply_amb. |
Render actions¶
Action commands are not executed on the spot: the engine waits 64 frames first, so pending work (freshly applied edits, background fetches) settles, and only then runs the action. The script resumes when the action completes. Note that captures take care of their own image quality: take_picture and friends reset the accumulator and render to a fixed convergence target, so the result does not depend on what happened before the command.
| Command | Description |
|---|---|
take_picture | Render and save a still picture (.jpg) at the configured resolution. |
take_atlas | Render a multi-viewpoint atlas contact sheet using the atlas layout and slot viewpoints. |
record_video | Record an animation video (.mp4) using the animation settings. |
record_spinner | Record a 360-degree turntable video. |
save_static | Export the scene as a regular .webex file. |
save_interactive | Export a self-contained interactive .webex for the viewer. |
Flow control¶
| Command | Description |
|---|---|
nop | Wait 64 frames and do nothing. Rarely needed: captures converge on their own; use it to give background work extra time. |
exit | Terminate the process. Appended automatically at the end of every script. |
Node names for set_string¶
| Node | Example | Resolves to |
|---|---|---|
| Special alias | ::globals | Scene globals. |
| Special alias | ::camera / ::main_camera | Main camera. |
| Special alias | ::render_pipeline / ::main_pipeline | Render pipeline. |
| Special alias | ::animation | Animation settings. |
| Layer name | MyLayer | Layer by name, no spaces. |
| Quoted layer name | "Metal Band" | Layer by name, spaces allowed. |
Execution model¶
- Commands execute sequentially, one instant command per frame, only while the engine is idle. While an action renders, the script pauses.
- Edit commands restart the render, so the next capture starts from a clean state.
- Every render action and
nopwaits 64 frames before starting. - When the script ends, the process exits (an
exitis always appended).
Basic operation¶
webex.exe is an ordinary Windows command-line program. You run it from a terminal, such as Command Prompt (cmd.exe) or PowerShell, typically from the folder that holds the executable and your scene file. Type a command like the ones below and press Enter, and the render runs. If you would rather not type it each time, paste the same line into a plain text file with a .bat extension (a DOS batch file) and double-click it to run, or chain several webex.exe calls in one .bat to render a whole series at once.
The same idea scales to any scripting language: anything that can launch a process, such as a Python script, a Node tool, or a CI job, can assemble the command line, run webex.exe, and move on to the next scene, which is how you wire the CLI into a larger automation pipeline.
Let an LLM write the scripts
Every command on this page is plain text, so a large language model can generate and drive these scripts for you. Point it at this CLI reference together with the Scene properties (USTR) list and the Content library names, so it knows the available commands, property ids, and material and ambience names, then ask it to turn a product database row or a plain-language brief into a ready-to-run -s or -S script.
Inline -s strings are handy for one or two commands. For anything longer, put the commands in a script file and pass it with -S: no quoting or ; juggling, comments and blank lines for structure, and the file is reusable across scenes. Both forms run the exact same commands.
Load a scene and take a picture, naming the output with -o:
webex.exe -k:ak_xxx -i:scene.3dm -o:render.jpg -s:take_picture
Set the resolution before capturing:
webex.exe -k:ak_xxx -i:scene.3dm -o:render.jpg -s:"set globals_resolution_w 1920;set globals_resolution_h 1080;take_picture"
The same commands as a script file, which is more readable and scales better as the list grows:
webex.exe -k:ak_xxx -i:scene.3dm -o:render.jpg -S:picture.txt
set globals_resolution_w 1920
set globals_resolution_h 1080
take_picture
Record a video, naming the output with -o:
webex.exe -k:ak_xxx -i:scene.3dm -o:video.mp4 -s:record_video
Render a slower turntable first (speed 3 is the Slow preset: 18"), using a script file:
webex.exe -k:ak_xxx -i:scene.3dm -o:video.mp4 -S:video.txt
set animation_speed 3
record_video
Real-world examples¶
The examples above isolate one feature each. These recipes are closer to real jobs: complete scripts you can adapt scene by scene. Each is shown as a script file (-S), the form we recommend; the same lines run inline with -s if you separate them with ;.
A framed still: resolution, the Resting Right pose (index 2), a centered camera, and round edges, then capture.
webex.exe -k:ak_xxx -i:scene.3dm -S:still.txt
set globals_resolution_w 1024
set globals_resolution_h 1024
set globals_pose_id 2
set_string ::camera camera_center_view 1
set render_pipeline_ssr_re_enable 1
take_picture
Dress two layers, light with a sun ambience rotated 90 degrees, and add a soft floor reflection.
webex.exe -k:ak_xxx -i:scene.3dm -S:look.txt
set globals_resolution_w 1280
set globals_resolution_h 768
apply_mtl Metal 01:Yellow Gold 18k
apply_mtl Gem 01:Diamond Fancy Pink
apply_amb sun:Ambience17s
set globals_ibl_angle 90
set globals_floor_mirror_enable 1
set globals_floor_mirror_weight 0.1
set_string ::camera camera_center_view 1
take_picture
A boomerang animation: pose and look, a black-shelf ambience, a tighter 19-degree H-FOV, and the Slow turntable speed (an 18-second rotation), then record. -o:my_video names the file (.mp4 is appended for you).
webex.exe -k:ak_xxx -i:scene.3dm -o:my_video -S:video.txt
set globals_resolution_w 1080
set globals_resolution_h 1080
apply_mtl Metal 01:Rose Gold 18k
set render_pipeline_ssr_re_enable 1
set globals_pose_id 2
apply_amb black:Ambience03b
set_string ::camera camera_center_view 1
set camera_hfov 19
set animation_speed 3
set animation_boomerang_enable 1
record_video
A raw .glb import at the YouTube resolution preset (index 3, 1920x1080): rename each mangled layer, give it a family, and dress it, then save the whole look as a dressing and capture. Rename before setting the family or applying a material, since later commands must use the new name.
webex.exe -k:ak_xxx -i:scene.glb -S:glb.txt
set globals_resolution_preset 3
set globals_pose_id 2
set_string ::camera camera_center_view 1
set_layer_alias Default 01:Gem 01
set_layer_family Gem 01:gemstone
apply_mtl Gem 01:Ruby India
set_layer_alias User 04:Metal 01
set_layer_family Metal 01:metal
apply_mtl Metal 01:Rose Gold 18k
set_layer_alias Default:Metal 02
set_layer_family Metal 02:metal
apply_mtl Metal 02:Yellow Gold 18k
set_layer_alias Heads:Metal 03
set_layer_family Metal 03:metal
apply_mtl Metal 03:Platinum 950
apply_amb sun:Ambience17s
export_dressing scene.webex_dressing
take_picture
Reuse three saved camera dressings to shoot the same model from three angles in one run. Each import_dressing resets the render, so every capture starts clean.
webex.exe -k:ak_xxx -i:scene.3dm -o:shot_%02d -S:sweep.txt
import_dressing camera01.webex_dressing
take_picture
import_dressing camera02.webex_dressing
take_picture
import_dressing camera03.webex_dressing
take_picture
What %02d counts
The index is the command number -- the [NN] echoed as each command runs -- not a capture counter. Here the three take_picture commands are the 2nd, 4th, and 6th commands, so the files land as shot_02.jpg, shot_04.jpg, shot_06.jpg. For exact, arbitrary filenames, drive separate runs from a batch file (next tab).
When you need each render saved under a specific name rather than an index, call the CLI once per variation from a Windows batch file. Each run loads a shared base dressing, keeping the camera and scene consistent, and changes only the material.
@echo off
webex.exe -k:ak_xxx -i:scene.3dm -o:scene_yellow_gold -s:"import_dressing base.webex_dressing;apply_mtl Metal 01:Yellow Gold 18k;take_picture"
webex.exe -k:ak_xxx -i:scene.3dm -o:scene_white_gold -s:"import_dressing base.webex_dressing;apply_mtl Metal 01:White Gold 18k;take_picture"
Run it by double-clicking the .bat, or from a terminal:
render_variations.bat
You can settle a house look once in the Excelsior Editor, and then stamp it across a whole catalog from the CLI. In the editor, dress a scene the way you like it, frame the product shot, and export the settings as a .webex_dressing file. That file defines a master look the CLI can import and reproduce.
Apply that dressing to every product and render, one run per scene. A .bat walks a folder of models (the renders folder must already exist):
@echo off
for %%f in (rings\*.3dm) do webex.exe -k:ak_xxx -i:"%%f" -o:"renders\%%~nf" -S:apply.txt
import_dressing house.webex_dressing
take_picture
To reuse only part of the look, filter by category on import. Here each product keeps its own materials and takes only the camera and ambience from the master:
webex.exe -k:ak_xxx -i:ring.3dm -s:"import_dressing camera,ambience:house.webex_dressing;take_picture"
Found a mistake?
We do our best to keep this reference accurate and in step with the product, but mistakes and omissions can slip through, and they are never intentional. If anything here looks wrong, incomplete, or unclear, please contact us and we will gladly fix it.