# Glb Compressor CLI

> 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.

- Skill: `kjanat/glb-compressor-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kjanat/glb-compressor-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kjanat/glb-compressor-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: kjanat (https://skillmd.com/u/kjanat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kjanat/glb-compressor-cli

---


# 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](https://dreamcli.kjanat.dev), 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

```sh
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

```sh
# 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:

1. **Cleanup** - dedup, prune, remove unused UVs (+ flatten/join/weld for
   static)
2. **Geometry** - merge by distance, remove degenerate faces, auto-decimate
3. **GPU** - instancing, vertex reorder, sparse encoding
4. **Animation** - resample keyframes, remove static tracks, normalize weights
5. **Textures** - compress to WebP (max 1024x1024)
6. **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.