@spatialpack/cli

@spatialpack/cli

Standards-first glTF / GLB / USDZ analyzer and optimizer. Drop a 3D model, get an honest before/after report. KTX2, WebP, AVIF, meshopt, Draco — the same pipeline you run in CI, on the command line. Every optimize records pre/post stats and a visual-diff regression gate; visual regressions are first-class failures, not warnings.

SpatialPack is post-production / pipeline tooling: it optimizes assets you already have. It does not generate models, replace your DCC tool, or host your files. Input and output are glTF / GLB or USD — no proprietary formats.

Install

npm i -g @spatialpack/cli
# or run without installing:
npx @spatialpack/cli --help

Most commands are pure compute and need nothing extra. The render-backed commands (visual-diff, bake-imposter, usdz-render, and --visual-diff-* gates) drive a headless Chromium via Playwright — install it once with:

npx playwright install chromium

Quickstart

spatialpack analyze model.glb                      # per-mesh / per-material / per-texture report (JSON)
spatialpack optimize model.glb -o out.glb -p web-mobile   # optimize against a preset
spatialpack readiness out.glb                      # commerce-readiness scorecard → ready|warnings|not-ready

Headline commands

Command	What it does
analyze <input>	Per-mesh, per-material, per-texture byte attribution for a .glb/.gltf. --out writes JSON, --html writes a report.
optimize <input> -o <out>	Run the optimize pipeline (meshopt, KTX2/WebP/AVIF textures, animation dedup, optional decimation) against a --preset (web-mobile | web-desktop | quality-max). Records before/after stats per pass. --visual-diff-out <dir> adds a Playwright SSIM/ΔE94 regression gate; --auto-recipe autotunes the pass combination.
recipe-search <input> -o <out>	Grid / beam search across optimization recipes, scoring the Pareto frontier of (bytes, visual fidelity). --winner-strategy smallest|balanced|perceptual-budget. Optional per-recipe visual-diff gate.
visual-diff <a> <b>	Side-by-side model-viewer capture + MAE / SSIM / ΔE94 between two GLBs. Requires Playwright Chromium.
readiness <input>	Commerce-readiness scorecard — conformance + AR Quick Look parity + geometry → ready | warnings | not-ready. Exits non-zero on not-ready. --usdz <path> adds AR structural + PBR-drift parity.
autocorrect <input>	Repair an asset (prune floaters, resize/clean via preset) and re-score commerce readiness. batch-autocorrect does it catalog-wide with a roll-up of readiness transitions.
export-usdz <input> -o <out>	Convert GLB → USDZ via the locally installed USD converter, with post-export structural validation.
validate-usdz <input>	Structural validation of a .usdz — no USD converter required. --source <glb> adds PBR round-trip drift checks; --render-diff pixel-compares textures.
conformance <input>	Asset Creation Guidelines 2.0 + USDZ round-trip conformance check. Exits 1 on FAIL.
ar-parity <input>	AR Quick Look parity gate (structural + numeric, no render). Exits 1 on FAIL.
budget <input>	Pass/fail budget check (preset file size + AR target sizes + extension compat). Pure JSON, exits 1 on fail.
batch <inputs...>	Optimize many assets in one run.

Run spatialpack --help for the complete surface, which also includes LOD / progressive-delivery bundles, Gaussian-splat compression (splat-*), texture dedup, GLB↔diff/patch, embedding-index + similar, MaterialX import/export, and USD usd-cat / usda-to-usdc / usd-compose.

CI usage

analyze, optimize, readiness, conformance, ar-parity, and budget emit stable JSON on stdout and set a non-zero exit code on failure, so they drop straight into a CI gate. The same code path powers the SpatialPack web analyzer and GitHub Action.

License

MIT. The underlying engine is @spatialpack/core (Functional Source License, FSL-1.1-ALv2). See LICENSE.