spine-cli

CLI for exported Spine 2D skeletal assets. Render animations to images/video, report skeleton info.

What it does

Operates on Spine runtime exports (.json + .atlas/.atlas.txt + PNG textures).

• render: rasterize an animation to pngseq (default), png (single frame), gif, mp4, webm, webp, apng.
• info: Spine version, animations + durations, skins, bone/slot/attachment/constraint counts, mesh/clipping flags, atlas pages/resolution + missing-texture check.

How it works

• Rendering: spine-ts WebGL backend in headless Chromium (Playwright), screenshotting frames. WebGL for full mesh + clipping fidelity (both common in targets).
• Version dispatch: bundles spine-ts 4.0 + 4.2, picks per-skeleton from embedded "spine" field (format broke at 4.1; targets straddle it).
• Input resolution: pass a .json; single sibling *.atlas.txt/*.atlas auto-resolved (--atlas overrides); textures relative to atlas dir. Also accepts dir or glob for batch.
• Video (mp4/webm): shells out to ffmpeg (detected on PATH). mp4 defaults white (no alpha); webm defaults transparent.
• Animated webp: shells out to img2webp (a libwebp tool), not ffmpeg. Every frame is a key frame (-kmax 0) so nothing blends across frames and transparency stays exact; ffmpeg's libwebp blends with no disposal control and leaves trails behind moving semi-transparent pixels. Lossless with full alpha by default; pass --quality 0-100 for a smaller lossy file.

Usage

spine-cli info <skeleton.json> [--atlas <path>] [--json] [--verbose]

spine-cli render <skeleton.json | dir | glob>
    [--atlas <path>]
    --animation <name|all>                     # error+lists names if multiple and omitted
    --format <pngseq|png|gif|mp4|webm|webp|apng> # default pngseq
    --out <path> | --out-dir <dir>
    --fps <n>                                   # default 30
    --scale <f> | --width <px> --height <px>    # default --scale 1.0
    --fit <declared|bounds|piece|shared>        # default declared (skeleton width/height)
    --piece <glob>                              # render only these slots; repeatable
    --skin <name>
    --duration <sec> --loops <n>
    --frame <t>                                 # single still for --format png
    --background <color|transparent>            # default transparent; white for mp4
    --quality <0-100>                           # webp lossy quality; omit for lossless
    --concurrency <n> --dry-run

Batch writes {skeleton}_{animation}.{ext} beside each input or into --out-dir.

If a skeleton has more than one animation, --animation <name|all> is required (the error lists the names). When a directory holds multiple atlases and none matches the skeleton basename, pass --atlas.

Pieces

Render a subset of a skeleton's slots as its own output. Each --piece is one or more comma-joined slot globs (*, ?); a slot joins the piece if any glob matches. --piece is repeatable, one output per flag, named {skeleton}_{animation}_{piece}.{ext}.

--fit controls the framing box, which matters when pieces are meant to stack as layers:

• piece: each piece tight to its own bounds. Smallest files; pieces do not align.
• shared: all selected pieces share one box (their combined bounds). Stack the layers and they realign.
• bounds: shared box spanning the whole skeleton (all slots). Same alignment, more margin.
• declared: shared box is the declared artboard.

Boxes are the union across every frame of the clip, so an animated piece keeps a stable size instead of jittering. piece and shared require at least one --piece.

# three stackable layers of one animation, aligned in the artboard
spine-cli render VaultSetup.json -a State0-OpenIdle --format apng --fit shared \
    --piece "Redux/VaultDoorIsolated/*" --piece "Chips/*" --piece "images/*"

Prerequisites

• Chrome or Chromium on the system (rendering runs headless via playwright-core, launched with channel: "chrome").
• ffmpeg on PATH only for mp4/webm; img2webp (from libwebp) on PATH only for webp. The image formats (pngseq, png, gif, apng) need nothing extra.

Scripts

| script | command | does | | -------------------- | ------------------------------ | -------------------------- | | pnpm build | build-harness.mjs && vp pack | build harness bundle + cli | | pnpm build:harness | build-harness.mjs | rebuild the browser bundle | | pnpm dev | vp pack --watch | rebuild the cli on change | | pnpm check | vp check | format + lint + typecheck |

The browser render harness (spine-ts 4.0 + 4.2) bundles to dist-harness/harness.js via esbuild; rerun pnpm build:harness after editing src/render/harness/.