Run Operations

run-operations — Run optimizations with the usdOptimize CLI

Drives the official command line tool to apply one or more operations to a USD stage and write the result. The CLI is documented in docs/cli.rst; per-operation arguments and tuning guidance are in docs/operations/ (one .rst per operation key); guidance on which operations to use is in docs/choosing-operations.rst.

What this skill covers

• The binary — locating usdOptimize for the platform/config.
• Usage — single op, chained ops, and config files.
• Preset configs — the ready-made stacks in config_presets/.
• Step 1 — validate the input path.
• Step 2 — assemble the operation source (inline, preset, or custom config).
• Step 3 — run the CLI and capture the log.
• Step 4 — summarize and offer to re-validate.
• Confirm before destructive ops — when to pause and ask.
• Build a config from validator findings — for issues run-validators --fix could not auto-resolve.
• Errors to handle — failure modes.

Companion skills: run-validators (validate + auto-fix), interpret-validators (decide what to do about non-auto-fixable issues), tune-parameters (iterate one operation's parameters), inspect-asset (confirm the stage has the prims an op targets).

The binary

_build/<platform>/<config>/bin/usdOptimize        # POSIX
_build\<platform>\<config>\bin\usdOptimize.bat     # Windows

Use the .bat on Windows, not usdOptimize.exe: it sets up the library path the executable needs. The bare .exe exits -1073741515 (STATUS_DLL_NOT_FOUND), and PATHEXT picks it first, so name the .bat.

<platform> is linux-x86_64, linux-aarch64, or windows-x86_64; <config> is release (default) or debug. List _build/ to pick the right one. The binary is self-contained (its rpath resolves the bundled USD and operation-plugin libraries), so no LD_LIBRARY_PATH / PYTHONPATH setup is needed — run it directly. If _build/ is missing, point at the build skill and stop; do not build it yourself.

Usage

Key flags (full list: usdOptimize --help and docs/cli.rst):

Single operation:

usdOptimize -i input.usd -o meshCleanup -a mergeVertices=true -a removeDegenerateFaces=true -w output.usd

Operation chain via a JSON config (the array shape used by -c):

[
  {"operation": "meshCleanup", "mergeVertices": true},
  {"operation": "decimateMeshes", "reductionFactor": 0.0, "maxMeanError": 0.01, "pinBoundaries": true}
]

usdOptimize -i input.usd -c chain.json -w output.usd

Preset configs

config_presets/*.json are ready-made stacks (see config-presets for the preset table and when to use each): safe-cleanup, memory-reduction, load-time-reduction, hierarchy-dedup (all lossless), and data-quality-baseline, mesh-count-reduction (bounded loss). Run one directly:

usdOptimize -i input.usd -c config_presets/safe-cleanup.json -w output.usd

To customize, copy a preset and edit the operation list. If the user is unsure what to run, safe-cleanup is the conservative, all-lossless default.

Step 1 — Validate the input

Reject a path that does not exist or is not a .usd* file before running. If no path was given, ask which USD file to optimize.

Step 2 — Assemble the operation source

Pick exactly one: inline -o/-a (one or two ops), a preset -c config_presets/<name>.json, or a custom config file you write. For argument names, types, and defaults, read the operation's docs/operations/<key>.rst. Empty paths (or meshPrimPaths) means "process the whole stage"; pass explicit prim paths to scope an op.

Step 3 — Run the CLI

Choose an output path (a temp dir or next to the input, per the user) and redirect to a log file rather than piping through tail (pipes buffer until exit). Heavy ops (decimation, occlusion removal, dedup at scale) can take minutes — launch as a long-running command (run_in_background: true in Claude Code; nohup/Start-Process elsewhere) and return control.

BIN=_build/linux-x86_64/release/bin/usdOptimize
OUT=<output path>
"$BIN" -i "<asset>" -c config_presets/memory-reduction.json -s -r -w "$OUT" > "$OUT.log" 2>&1

$Bin = "_build\windows-x86_64\release\bin\usdOptimize.bat"
$Out = "<output path>"
& $Bin -i "<asset>" -c config_presets\memory-reduction.json -s -r -w $Out *> "$Out.log"

Tell the user it is running and that you will report results when it finishes.

Step 4 — Summarize and offer to re-validate

Show the last ~40 lines of the log (the -s stats and -r report, per-op timings, the final "UsdOptimize finished" line). Then:

Optimization complete.
  Output: <OUT> (<size>)
  Log:    <OUT>.log

To confirm the result, validate the optimized stage:
  /run-validators <OUT>

If the CLI exits non-zero, surface the failing line from the log; don't auto-retry. A common cause is an argument key mismatch, and the two entry points differ: -a key=value rejects an unknown key (Error: invalid argument specified: <key>, exit 1), while a -c config file warns and continues, running the operation with the default. Verify keys against docs/operations/<key>.rst.

Confirm before destructive ops

Some operations permanently alter geometry or remove prims. When the requested chain contains any of these, list them, explain what each does, and confirm before running:

If the user is uncertain, fall back to config_presets/safe-cleanup.json.

Build a config from validator findings

run-validators --fix already applies every fix the validators can apply automatically. Reach for this section only for the issues it reported as unfixed (which interpret-validators will have triaged), because they need a decision:

1. From the interpret-validators report, take the operation each unfixed issue maps to and the parameters the user chose.
2. Group ops by family — one meshCleanup with the union of needed flags rather than several.
3. Order the chain sensibly (clean topology before decimation; dedup before decimation). docs/choosing-operations.rst covers ordering by goal.
4. Show the final JSON and confirm before running, calling out any destructive op from the table above.

Errors to handle

Purpose

Apply a chain of Usd Optimize operations to a USD stage with the usdOptimize CLI — inline, from a preset config, or from a custom JSON config — and write the result. Closes the validate → fix → re-validate loop for issues that need a manual operation.

Prerequisites

• A built repo so _build/<platform>/<config>/bin/usdOptimize exists.
• A USD asset (.usd / .usda / .usdc / .usdz).
• An operation source: inline -o/-a, a preset, or a JSON config file.

Limitations

• Executes operations; it does not author new ones — use new-operation.
• For read-only "what would this do" analysis, prefer run-validators (or add -an to a CLI run); the validators already aggregate analysis results.
• Won't trigger a build — if _build/ is missing, use the build skill.