glb-compressor CLI
Command-line tool for compressing GLB/glTF 3D model files. Supports glob
patterns, configurable presets, mesh simplification, and batch processing. Built
on dreamcli, so --help, --version, --quiet,
and --json are framework-owned root flags.
Binary Name
glb-compressor (installed via npm/bun) or bun run cli (from source).
Usage
glb-compressor <files...> [options]
Options
| Flag |
Description |
Default |
-o, --output <dir> |
Output directory |
Same as input (with -compressed suffix) |
-p, --preset <name> |
Compression preset |
default |
-s, --simplify <0-1> |
Mesh simplification ratio (e.g. 0.5 = 50%) |
None |
-k, --keep-nodes |
Preserve node hierarchy, node and material names, for parts moved at runtime by name (wheels, doors) |
false |
-f, --force |
Overwrite existing output files |
false |
-q, --quiet |
Suppress informational output (root flag, for scripting) |
false |
--json |
Emit machine-readable JSON output (root flag) |
false |
-h, --help |
Show help text |
|
-V, --version |
Show version |
|
Presets
| Preset |
Behavior |
default |
Conservative, preserves all detail |
balanced |
Moderate animation quantization, 24 Hz resample |
aggressive |
Strong animation quantization, 15 Hz resample (best for avatars) |
max |
Aggressive + supercompression + lower vertex precision |
Examples
# Compress a single file
glb-compressor model.glb
# Aggressive preset to an output directory
glb-compressor model.glb -p aggressive -o ./out/
# Batch compress with glob, overwrite existing
glb-compressor *.glb -f -p balanced
# Quiet mode for CI/scripts (exit code 0 = success, 1 = failure)
glb-compressor model.glb -q -p max
# Simplify mesh to ~50% vertex count
glb-compressor model.glb -s 0.5
# From source (development)
bun run cli -- model.glb -p aggressive -o ./compressed/
Output Naming
Output files are named <input>-compressed.glb. When -o is specified, files
are placed in that directory. Without -o, output is written alongside the
input file.
Exit Codes
| Code |
Meaning |
0 |
All files compressed successfully |
1 |
One or more files failed, or invalid simplify ratio |
2 |
Parse or constraint error (e.g. unknown preset) |
Pipeline
The CLI runs the same 6-phase pipeline as the library:
- Cleanup - dedup, prune, remove unused UVs (+ flatten/join/weld for
static)
- Geometry - merge by distance, remove degenerate faces, auto-decimate
- GPU - instancing, vertex reorder, sparse encoding
- Animation - resample keyframes, remove static tracks, normalize weights
- Textures - compress to WebP (max 1024x1024)
- Final - gltfpack (preferred) or meshopt WASM fallback
Skinned models are auto-detected and take a conservative path that skips
transforms known to break skeleton hierarchies.
Skinned Model Awareness
When a GLB contains skins (e.g. avatars), the CLI automatically skips: flatten,
join, weld, mergeByDistance, reorder, quantize, and auto-decimate. This prevents
broken skeleton hierarchies, vertex weight denormalization, and mesh clipping
artifacts.
Dependencies
- gltfpack (optional): If found in
$PATH, used for final compression (best
results). Falls back to meshopt WASM if unavailable.
- sharp: Used for texture compression to WebP.
1---2name: glb-compressor-cli3description: Compress GLB/glTF 3D models using the glb-compressor CLI. Use when running compression from the command line, writing shell scripts that compress models, or integrating into CI/CD pipelines.4license: MIT5---67# glb-compressor CLI89Command-line tool for compressing GLB/glTF 3D model files. Supports glob10patterns, configurable presets, mesh simplification, and batch processing. Built11on [dreamcli](https://dreamcli.kjanat.dev), so `--help`, `--version`, `--quiet`,12and `--json` are framework-owned root flags.1314## Binary Name1516`glb-compressor` (installed via npm/bun) or `bun run cli` (from source).1718## Usage1920```sh21glb-compressor <files...> [options]22```2324## Options2526| Flag | Description | Default |27| ---------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- |28| `-o, --output <dir>` | Output directory | Same as input (with `-compressed` suffix) |29| `-p, --preset <name>` | Compression preset | `default` |30| `-s, --simplify <0-1>` | Mesh simplification ratio (e.g. 0.5 = 50%) | None |31| `-k, --keep-nodes` | Preserve node hierarchy, node and material names, for parts moved at runtime by name (wheels, doors) | `false` |32| `-f, --force` | Overwrite existing output files | `false` |33| `-q, --quiet` | Suppress informational output (root flag, for scripting) | `false` |34| `--json` | Emit machine-readable JSON output (root flag) | `false` |35| `-h, --help` | Show help text | |36| `-V, --version` | Show version | |3738## Presets3940| Preset | Behavior |41| ------------ | ---------------------------------------------------------------- |42| `default` | Conservative, preserves all detail |43| `balanced` | Moderate animation quantization, 24 Hz resample |44| `aggressive` | Strong animation quantization, 15 Hz resample (best for avatars) |45| `max` | Aggressive + supercompression + lower vertex precision |4647## Examples4849```sh50# Compress a single file51glb-compressor model.glb5253# Aggressive preset to an output directory54glb-compressor model.glb -p aggressive -o ./out/5556# Batch compress with glob, overwrite existing57glb-compressor *.glb -f -p balanced5859# Quiet mode for CI/scripts (exit code 0 = success, 1 = failure)60glb-compressor model.glb -q -p max6162# Simplify mesh to ~50% vertex count63glb-compressor model.glb -s 0.56465# From source (development)66bun run cli -- model.glb -p aggressive -o ./compressed/67```6869## Output Naming7071Output files are named `<input>-compressed.glb`. When `-o` is specified, files72are placed in that directory. Without `-o`, output is written alongside the73input file.7475## Exit Codes7677| Code | Meaning |78| ---- | --------------------------------------------------- |79| `0` | All files compressed successfully |80| `1` | One or more files failed, or invalid simplify ratio |81| `2` | Parse or constraint error (e.g. unknown preset) |8283## Pipeline8485The CLI runs the same 6-phase pipeline as the library:86871. **Cleanup** - dedup, prune, remove unused UVs (+ flatten/join/weld for88 static)892. **Geometry** - merge by distance, remove degenerate faces, auto-decimate903. **GPU** - instancing, vertex reorder, sparse encoding914. **Animation** - resample keyframes, remove static tracks, normalize weights925. **Textures** - compress to WebP (max 1024x1024)936. **Final** - gltfpack (preferred) or meshopt WASM fallback9495Skinned models are auto-detected and take a conservative path that skips96transforms known to break skeleton hierarchies.9798## Skinned Model Awareness99100When a GLB contains skins (e.g. avatars), the CLI automatically skips: flatten,101join, weld, mergeByDistance, reorder, quantize, and auto-decimate. This prevents102broken skeleton hierarchies, vertex weight denormalization, and mesh clipping103artifacts.104105## Dependencies106107- **gltfpack** (optional): If found in `$PATH`, used for final compression (best108 results). Falls back to meshopt WASM if unavailable.109- **sharp**: Used for texture compression to WebP.
kjanat