EntVista Hub + Metrixel CLI Reference

The command-line reference for EntVista Hub (sign-in and licence seats) and Metrixel (the dataset pipeline), current as of 2026.3.1. We will cover every option, the defaults, the plans each may need... all of this with examples for headless and automated workflows.

Metrixel's CLI is a preview surface: pin the product version your automation runs against, and use the installed build's --help if it and this page ever disagree.

Modification history

1. Running the commands

The examples use entvistahub and metrixel. Those short names exist on Linux after running the tarball's ./install.sh, which links both into ~/.local/bin. On macOS and Windows, run the binary from its install folder instead, for example:

EntVista Hub installs the same way, under EntVistaStudio/EntVistaHub/<version>/.

Close the Metrixel app before using the CLI. While the desktop app is open, a CLI run exits with an error, and --version / --help print nothing. Always write the mode as --mode cli.

2. EntVista Hub CLI

Metrixel has no separate command-line login. EntVista Hub owns sign-in and the subscription session. Sign in through EntVista Hub once on the host; later Metrixel CLI runs on the same host reuse that session.

On a headless machine, sign-in uses a device code: the terminal prints a short code and an address, and you approve the sign-in in a browser on any other device.

Commands

A first run on a new host:

entvistahub --mode cli auth login
entvistahub --mode cli auth status

metrixel --version
metrixel --help

Keep EntVista Hub installed on the same host. Metrixel gets sign-in, subscription and plan state from the Hub, and starts it if it is not already running.

3. Metrixel CLI

Every pipeline run begins with:

metrixel --mode cli

Before building automation around an installation:

metrixel --version    # includes the build ID — record it with generated datasets
metrixel --help

Boolean options always take a value: write --xray true (or --xray=true), never a bare --xray. true/false, 1/0, yes/no and on/off are all accepted.

Plans. Rendering, texture extraction and PyTorch mesh export are available on every plan, including the free signed-in tier. Batch mode, TIFF, SDF export, Motion Retargeting, Mesh-Aware Correction and Clipping (Penetration) Visualisation need the Professional plan.

3.1 Core input and output

Inputs: FBX, OBJ, glTF/GLB and STL. Files over 200 MB are skipped.

Output layout: <output>/assets/<asset>/{images,meshes,textures,animations,sdf}/ plus manifest.json.

Example — one asset

metrixel --mode cli \
  --gen_mode single \
  --model_file /data/input/character.glb \
  --output /data/output \
  --gen_sdf false

--gen_sdf false keeps a Standard or free run from reporting a skipped SDF stage (see Exit codes); Professional users can leave it out.

Example — recursive batch (Professional)

metrixel --mode cli \
  --gen_mode batch \
  --input /data/input \
  --output /data/output \
  --include_formats=fbx,glb \
  --manifest=true

3.2 Image and animation capture

Images are written to <output>/assets/<asset>/images/.

Example — 12 views, PNG, every fourth animation frame

metrixel --mode cli \
  --gen_mode single \
  --model_file /data/input/character.fbx \
  --output /data/output \
  --width 1024 --height 1024 \
  --frame_format png \
  --camera_step 30 \
  --frames_per_second 30 \
  --frame_range=0:120 \
  --frame_stride=4 \
  --gen_sdf false

Example — one camera angle

metrixel --mode cli \
  --gen_mode single \
  --model_file /data/input/character.glb \
  --output /data/output \
  --camera_step 0 \
  --gen_sdf false

Example — x-ray alongside the normal render

metrixel --mode cli \
  --gen_mode single \
  --model_file /data/input/character.glb \
  --output /data/output \
  --xray true \
  --gen_sdf false

Each frame is written twice: 000_000_000_0000.jpg and 000_000_000_0000_xray.jpg. No correction, retarget or Professional plan is needed; like every render, it requires signing in through EntVista Hub.

3.3 Mesh tensors and SDF

Example — reproducible CPU SDF (Professional)

metrixel --mode cli \
  --gen_mode single \
  --model_file /data/input/mesh.glb \
  --output /data/output \
  --gen_sdf=true \
  --sdf_resolution=64 \
  --sdf_backend=cpu \
  --manifest=true

3.4 Motion Retargeting (Professional)

Retargeting takes a target bone-map setting plus either a source-list file or a source folder — not both. Sources can be FBX, glTF/GLB or BVH.

Target rig

--bone_map_target auto
--bone_map_target /path/to/custom_target_map.json

auto identifies the target's rig from the asset itself.

Source-list mode

--retarget_sources takes a JSON list file, not a motion file directly.

Example sources.json:

[
  {"file": "/mocap/walk.fbx", "bone_map": "auto"},
  {"file": "/mocap/run.bvh", "bone_map": "auto"}
]

metrixel --mode cli \
  --gen_mode single \
  --model_file /characters/target.fbx \
  --output /data/output \
  --bone_map_target auto \
  --retarget_sources /config/sources.json

Source-folder mode

metrixel --mode cli \
  --gen_mode single \
  --model_file /characters/target.fbx \
  --output /data/output \
  --bone_map_target auto \
  --retarget_source_folder /mocap/library

The folder is searched recursively for FBX, glTF/GLB and BVH files. Each source's rig is identified independently (--retarget_source_bone_map auto, the default), so one folder can mix rig types.

Retarget controls

3.5 Mesh-Aware Correction and Penetration Visualisation (Professional) — 2026.3.1

Both run as part of Motion Retargeting, so a retarget must be configured (section 2.4).

Example — correction

metrixel --mode cli \
  --gen_mode single \
  --model_file /characters/target.fbx \
  --output /data/output \
  --bone_map_target auto \
  --retarget_sources /config/sources.json \
  --mesh_aware_correction true \
  --correction_quality accurate

Example — correction plus x-ray and heat map

metrixel --mode cli \
  --gen_mode single \
  --model_file /characters/target.fbx \
  --output /data/output \
  --bone_map_target auto \
  --retarget_sources /config/sources.json \
  --mesh_aware_correction true \
  --penetration_visualisation true \
  --correction_quality fast

3.6 Project files

With a project loaded, the manifest and SDF format options (--manifest, --sdf_resolution, --sdf_format, --sdf_backend, --include_formats) still apply from the command line. Whether SDF and .pt are generated at all follows the project.

Example — run a saved project

metrixel --mode cli \
  --project /projects/dataset.aproj \
  --sdf_resolution=128 \
  --manifest=true

4. Combined headless workflow

A fresh headless host uses the two applications in this order:

# 1. Sign in once through EntVista Hub (--offline if the host must stay signed in through restarts).
entvistahub --mode cli auth login
entvistahub --mode cli auth status

# 2. Record the Metrixel build being automated.
metrixel --version

# 3. Run the dataset pipeline (batch and SDF: Professional).
metrixel --mode cli \
  --gen_mode batch \
  --input /data/assets \
  --output /data/dataset \
  --include_formats=fbx,glb \
  --width 1024 --height 1024 \
  --camera_step 30 \
  --gen_pt=true \
  --gen_sdf=true \
  --sdf_resolution=64 \
  --sdf_backend=auto \
  --manifest=true

# 4. Before tearing the host down, release the seat.
entvistahub --mode cli auth logout     # auth logout --all for an --offline sign-in

5. Automation notes

Exit codes

• Turn off what your plan doesn't include (--gen_sdf false on Standard and free) so a clean run exits 0 rather than 12.
• Pin the Metrixel version used by CI or dataset production while the CLI is a preview surface, and record metrixel --version (which includes the build ID) with generated datasets and support reports.
• Prefer --project when a long set of render settings is shared between the GUI and the CLI; prefer explicit options when a job should be self-contained in a script.
• --help also lists some internal diagnostic options (candidate, BVH and penetration-label tools). They are unsupported and may change without notice.

6. Checking the installed build

entvistahub --mode cli auth status
metrixel --version
metrixel --help

When this reference and an installed build disagree, the installed build's --help is authoritative for that version.