CLI guide¶

Install and verify the CLI¶

The CLI is a licensed Windows distribution, not a public npm package. When access is approved, we provide a folder containing webex.exe and its required DLLs, plus a CLI-enabled ak_... API key. Keep the supplied files together.

Extract the supplied folder to a normal writable location, for example C:\ExcelsiorCLI.
Open PowerShell or Command Prompt in that folder.
Run webex.exe --help. A command list confirms that Windows can start the program.
Put a test .3dm, .glb, or .webex scene in the folder and run the first-picture command below.

./webex.exe -k:ak_xxx -i:scene.webex -o:first-picture.jpg -s:take_picture

On success, first-picture.jpg appears in the folder and the process exits with code 0. Exit codes are 0 for success, 1 for usage or input preflight failures, 2 when one or more script commands report an error, and 255 when the API key is rejected. Treat any nonzero value as failure. Keep the API key out of source control and shared logs. If Windows reports a missing DLL, restore the complete supplied distribution rather than downloading individual DLLs.

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). Choose either `-S` or `-s`, never both. We recommend `-S` for more than a couple of commands.
`-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.
`-u:<mm\|cm\|m>`	optional	Override units when importing a `.glb`. Ignored with a warning for other input formats.
`-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.
set_material and explicit-node set_property understand double quotes around layer or 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_property <ustr> <value>`	Preferred spelling of `set`. It infers the target from the `globals_`, `dressing_`, `animation_`, `camera_`, or `render_pipeline_` USTR prefix. See the properties reference.
`set_property <node> <ustr> <value>`	Set a property on an explicit node or layer when its node cannot be inferred from the USTR.
`get_property <node> <ustr>`	Print one property's current value. The node is explicit because reads do not use the setter's prefix inference.
`center_view`	Re-center the camera on the current product. This is the public button-style action; it takes no fake value.

For example, set the inferred camera property and then read it back through the explicit camera node:

set_property camera_hfov 19
get_property ::camera camera_hfov

Backward compatibility

Existing set <ustr> <value> scripts remain supported and execute through the exact same implementation as two-argument set_property. Existing explicit-node set_string <node> <ustr> <value> scripts remain supported as aliases of the three-argument set_property form.

Materials and ambience¶

Command	Description
`set_material <layer> <material>`	Preferred material setter. Quote a layer containing spaces; the rest of the line is the material name. Both names are case-sensitive.
`apply_ambience <shelf>:<name>`	Apply an ambience preset. The shelf and preset name are case-sensitive.

The old apply_material, apply_mtl, and apply_amb spellings remain supported aliases.

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_property "<layer>" obj_visible 0`	Hide a layer (or show it with `1`) through the explicit-node overload.

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.

Parts and mannequin¶

Command	Description
`merge_part <id> <file>`	Add a `.webex` or `.glb` part. Reusing an id atomically replaces that part.
`remove_part <id>`	Remove one keyed part. The reserved `__mannequin` id cannot be removed this way.
`clear_parts`	Remove all keyed parts.
`apply_mannequin <file\|none>`	Replace the matte mannequin from a `.webex` file, or remove it with `none`.

Tooling commands¶

These unsupported internal commands are present in the Windows CLI but may change without notice.

Command	Description
`list_catalog_json`	Emit the PAK catalog and current scene layers as JSON between marker lines.
`validate_webex_decode <file>`	Internal decoder parity check.
`bake_mannequin`	Internal authoring step that bakes the `MEX_ANCHOR` mannequin marker.
`take_picture_alpha`	Unsupported internal product-cutout PNG capture.
`profile [turns]`	Internal render profiler; `turns` must be a positive integer.

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 for `apply_ambience`.

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.
`draft_video`	Quickly draft an animation (`.mp4`) with one sample per frame.
`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. Returns 0 after a clean run and 2 when any command reported an error.

Node names for get_property and explicit set_property¶

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 nop waits 64 frames before starting.
When the script ends, the process exits (an exit is always appended).

Ready to build a complete batch? Continue with the CLI examples, or use the commands reference when you need a concise lookup table.