CLI Image and Animation Export

Export a saved .resprite project as a single PNG, a PNG frame sequence or a regular sprite sheet. Animation exports include a manifest.json describing the images and playback. Images use the original canvas size, transparent backgrounds, zero padding and 1× scale. Blank frames are retained.

This guide uses resprite-cli as shorthand. Set up the actual invocation using the platform guide: "$cli" for macOS / Linux AppDir, & $cli for Windows PowerShell, or "$cli" --cli for Linux AppImage. In your terminal, enter the directory containing the saved hero.resprite before running the examples. CLI exports use their own options and do not read editor export preferences. Each example uses a different destination; leave those destinations absent on the first run and create their parent directories beforehand.

Exporting a single frame

resprite-cli export image hero.resprite --output hero-still.png --frame 0

This creates hero-still.png beside the project, compositing visible layers and retaining transparency. Frame indices start at 0. To replace that PNG later, repeat the command with --overwrite.

Exporting a frame sequence

resprite-cli export frames hero.resprite --output hero-frames

On success, hero-frames/manifest.json maps frames to images stored under its builds/ directory. Each source frame is exported once per layer unit. Reverse and ping-pong playback are represented in the manifest without duplicating PNGs.

Exporting a regular sprite sheet

resprite-cli export sheet hero.resprite --output hero-sheet --columns 8

Read the image paths and frame regions from hero-sheet/manifest.json. --columns sets the number of columns per row; it must be a positive integer and defaults to 8. Unused slots in the last row remain transparent. The two examples use separate output directories so you can try both.

Selecting a clip and splitting layers

Run resprite-cli inspect hero.resprite, find the desired clip in the result's clips array, and copy its id. Replace CLIP_ID below with that value:

resprite-cli export sheet hero.resprite --output hero-clip --clip-id CLIP_ID --split-layers

• --clip-id selects one clip. Without it, the entire timeline is exported. Use clips[].id from inspect to distinguish clips, including those with duplicate names. An ID that cannot be found returns exit code 2.
• --split-layers splits visible layers using the editor's group splitting rules. Groups set not to split become single export units; hidden layers are excluded. Without this option, all visible layers are composited together.
• Add --dry-run to inspect the actual layer units and output plan; see Previewing and running.

Reading exported assets

A typical directory looks like this; use the manifest for actual image names:

hero-sheet/
  manifest.json
  builds/
    <buildId>/
      sprite.png

After the process succeeds, read manifest.json once and load the animation as follows:

1. Select an entry in animations and one of its tracks entries.
2. Follow that track's regions indices in order to read frame regions from the top-level regions array.
3. Use each region's image index to find an entry in images. Resolve its path relative to the directory containing manifest.json.
4. Display the image's x/y/width/height rectangle for durationMs milliseconds, then advance to the next region. For split-layer exports, each track represents one layer export unit.

This excerpt from a one-frame project with no clips shows those relationships. Version, source and integrity fields are omitted; <buildId> represents the generated directory name:

{
  "images": [
    {"path": "builds/<buildId>/sprite.png", "width": 16, "height": 16}
  ],
  "regions": [
    {"image": 0, "layerUnit": 0, "sourceFrame": 0, "frameId": "frame-1",
     "x": 0, "y": 0, "width": 16, "height": 16,
     "durationUnits": 1000, "durationMs": 100}
  ],
  "tracks": [{"layerUnit": 0, "layerIds": null, "regions": [0]}],
  "animations": [
    {"id": null, "name": "timeline", "direction": "Forward",
     "tracks": [{"layerUnit": 0, "regions": [0]}]}
  ]
}

At 10 FPS, region 0 takes a 16 × 16 rectangle from the top-left of image 0 and displays it for 100 milliseconds. All indices start at 0. Coordinates start at the image's top-left corner and use output pixels.

animations[].tracks[].regions already accounts for forward, backward or ping-pong playback. Play the indices in order without applying direction again. durationMs may be fractional; accumulate precise time instead of rounding each frame, which causes drift. Repeated references to a region use that region's duration.

Updating and cleaning up

For a first export, the output directory must not exist and its parent must already exist. Keep the source project outside the output directory. To update the sprite sheet created above, run:

resprite-cli export sheet hero.resprite --output hero-sheet --columns 8 --overwrite

--overwrite only updates a directory created by this CLI whose manifest and current images pass integrity checks. It cannot take over an ordinary directory or repair damaged outputs. The manifest includes integrity information and does not support manual editing; export again to change its contents.

Updates retain old builds so programs that have already read an old manifest can finish loading. Old builds and interrupted-export leftovers are not automatically removed, so the output directory may continue to grow. Always load images through the manifest; do not scan builds or infer filenames.

Concurrent exports to the same directory are not allowed. On output_busy / exit code 4, wait for the active job to finish before retrying. The retained .resprite_cli_lock_<digest> file in the output parent is normal; its presence does not mean a job is still running. Do not delete lock files or clean related directories until all CLI jobs have stopped. Before cleanup, also ensure no program is reading old builds.

A timeout or forced termination can leave newly exported assets without a success report. Treat the process as failed, inspect the manifest and assets, then decide whether to retry. Rendering failures do not overwrite old assets file by file, but this is not a power-loss recovery guarantee.

For all manifest fields and precise timing, see the format reference. See limits for output budgets and unsupported operations.