CLI Command and Format Reference
Use this page to look up CLI syntax, JSON fields and limits. For installation paths and the applicable CLI version, start with Quick start. The syntax below uses resprite-cli as shorthand; angle brackets mark values to replace and square brackets mark optional arguments. Do not type the brackets.
Command syntax
resprite-cli --help
resprite-cli --version
resprite-cli inspect <file.resprite>
resprite-cli export image <file.resprite> --output <file.png> [--frame N] [--overwrite] [--dry-run]
resprite-cli export frames <file.resprite> --output <directory> [--clip-id ID] [--split-layers] [--overwrite] [--dry-run]
resprite-cli export sheet <file.resprite> --output <directory> [--columns N] [--clip-id ID] [--split-layers] [--overwrite] [--dry-run]
resprite-cli export --config <file.json> [--dry-run]
resprite-cli batch --config <file.json> [--dry-run]
Command options
| Option | Meaning and default |
|---|---|
--output PATH | Required destination for direct exports; its parent must exist |
--frame N | Image only; zero-based non-negative integer, default 0 |
--columns N | Sheet only; positive integer, default 8 |
--clip-id ID | Frames/sheet only; clip's first-frame ID from inspect; omitted means the whole timeline |
--split-layers | Frames/sheet only; split visible layer units using the editor's group rules; omitted means composite |
--overwrite | Allow replacement; omitted means reject existing output. Animation directories must be intact CLI outputs |
--dry-run | Validate and return a plan without publishing; accepted for direct exports, configured exports and batches |
--config PATH | Read schema 1 JSON; one job for export, 1–100 jobs for batch |
--help / --version | Return command help / CLI implementation version as text |
Unknown, duplicate or mode-inappropriate options are rejected. With --config, the only additional option is --dry-run; edit the configuration to change export settings. Command-line relative paths use the current working directory. Quote paths containing spaces. Existing outputs require explicit overwrite permission even during a dry run.
Configuration schema
The configuration root accepts only schemaVersion and jobs; the version must be integer 1. Unknown fields, incorrect types and options that do not apply to the selected mode are rejected. Strings are not implicitly converted to booleans or numbers. Configuration files do not execute scripts, expand wildcards or read editor settings.
| Job field | Applicability and default |
|---|---|
mode, source, output | Required non-empty strings; mode is image / frames / sheet, input is .resprite |
overwrite | All modes; boolean, defaults to false |
frame | image; zero-based non-negative integer, defaults to 0; output must end in .png |
columns | sheet; positive integer, defaults to 8 |
clipId | frames / sheet; non-empty string from inspect's clips[].id |
splitLayers | frames / sheet; boolean, defaults to false |
See Configuration and batch exports for complete configuration files. Relative paths in JSON are resolved against the configuration file's directory.
Inspecting a project
To inspect frames and layers or obtain a clip ID, run:
resprite-cli inspect hero.resprite
The command returns the project structure as JSON without modifying the source or creating outputs. It still loads project images and requires a usable graphics environment. Missing images or a damaged document produce input errors.
For example, a clips entry may look like this. Pass its id to --clip-id to select that clip. IDs also distinguish clips with duplicate names:
{
"id": "frame-walk-start",
"name": "Walk",
"firstFrame": 0,
"lastFrame": 1,
"direction": "Forward",
"playbackFrames": [0, 1]
}
Results and exit codes
When integrating through a process API, pass the executable path and argument array separately. stdout uses UTF-8. Inspection, export, dry runs and normally completed batches return one JSON object; --help and --version return text. Diagnostics go to stderr and may include engine logs. Do not merge the streams before parsing JSON or require stderr to be empty.
| Exit code | Meaning and action |
|---|---|
| 0 | Success; read the stdout result |
| 2 | Invalid arguments, configuration or output plan; correct the options before retrying |
| 3 | Input file or document error; check the source project and configuration file |
| 4 | Output path, overwrite, busy destination or write failure; check the target and permissions |
| 5 | Rendering or encoding failure; retain stderr diagnostics |
| 6 | At least one batch job failed; read the per-job results in stdout |
| 70 | Internal error, startup failure or timeout; retain diagnostics and check for completed outputs |
Single-job failures and errors before a batch starts leave stdout empty. Normally completed batches return a summary even with exit code 6. Internal errors abort immediately; a timeout or forced termination can leave outputs without a final report. See batch failure handling.
All successful results include schemaVersion: 1, status: ok and cliVersion. Batch summaries also include these fields, but use status: error when any job fails.
| Result type | Main fields |
|---|---|
| Image export | Absolute source and output, plus frame, width and height |
| Animation export | source, output, mode, manifest, imageCount, regionCount |
| Inspection | action: inspect, absolute source, sourceSha256, canvas, frameRate, durationScale, frames, layers, clips, limits |
| Image dry run | action: plan, dryRun: true, mode: image, source and destination, frame index, dimensions, source digest, totalPixels and destination files |
| Animation dry run | action: plan, dryRun: true, source and destination, mode, manifest destination, image/region counts, totalPixels, warnings, imagePathPattern and plan |
| Batch summary | action: batch, dryRun, succeeded, failed, results; each entry has index, exitCode and the export/dry-run result or failure details |
In inspect, frames provides index, stable id, durationUnits and durationMs. layers provides the original-order index, id, name, parentId, kind, its own visible / opacity, renderVisible including parent-group visibility, and splitAsUnit for groups exported as a single unit. clips contains the fields shown above; playbackFrames already accounts for playback direction. See the Animation JSON reference for timing rules.
sourceSha256 identifies the source file contents actually read. An animation dry run stores its source digest in plan.source.sha256; plan includes image dimensions, regions, tracks and animations; use plan.tracks to inspect actual layer units. Published image paths use builds/<buildId>/<image.path>. Dry runs do not render images and therefore provide neither image SHA-256 values nor buildId. Do not consume a plan as a published manifest.
Animation manifest
manifest.json uses schemaVersion: 1:
| Field | Meaning |
|---|---|
schemaVersion / cliVersion / mode | Manifest format version, CLI version and export mode (frames / sheet) |
kind / buildId | Fixed identifier resprite-animation-export and build content digest; preserve these values |
source | Original project filename name and sha256 of the contents actually read; no absolute source path |
canvas / frameRate / durationScale | Original canvas dimensions, FPS and duration multiplier scale (1000) |
images | Image path relative to the manifest directory, using /; dimensions and sha256 |
regions | Image index, layer unit, source frame index, stable frame ID, rectangle coordinates and dimensions, durationUnits and durationMs |
tracks | Layer units and region indices in source-frame order; layerIds: null means all visible layers are composited, while an array lists the layer IDs included in the unit |
animations | Clip ID, original name, direction and playback region indices per track; projects without clips receive an animation named timeline with id: null |
A clip's ID is its first-frame ID and can be passed to --clip-id. The generated timeline has no selectable clip ID. Frames outside clips remain in the top-level tracks.
Precise duration is durationUnits × 1000 / (durationScale × frameRate) milliseconds, currently equivalent to durationUnits / frameRate. Identical PNG byte digests across platforms are not guaranteed.
For the loading sequence and an annotated excerpt, see Reading exported assets. The manifest includes integrity information and must not be edited manually.
Limits
| Item | Current limit |
|---|---|
| Input | Saved .resprite files only; unsaved edits are not read |
| Configuration | At most 1 MiB, containing 1–100 jobs |
| Output dimensions | At most 16,384 pixels per image edge and 16,777,216 output pixels across each job, including image mode |
| Output count | At most 100,000 images per job |
| Execution time | At most 120 seconds per invocation, including all batch jobs |
Exceeding the output budget returns exit code 2 before rendering. Inspection is not subject to the output pixel budget. Cropping, scaling, arbitrary frame ranges, layer selection by name, packed atlases, incremental builds and watch mode are not supported. Old builds are not automatically removed; see Updating and cleaning up.