Skip to main content

CLI Configuration and Batch Exports

Use JSON configuration to repeat exports or integrate multiple projects into a build workflow. 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.

Creating a configuration​

Save the following as build.json beside the saved hero.resprite and enemy.resprite files. Replace project names as needed and remove unwanted jobs from jobs. None of the three destinations should exist before the first run.

{
  "schemaVersion": 1,
  "jobs": [
    {"mode": "image", "source": "hero.resprite", "output": "batch-hero.png", "frame": 0},
    {"mode": "frames", "source": "hero.resprite", "output": "batch-hero-frames"},
    {"mode": "sheet", "source": "enemy.resprite", "output": "batch-enemy-sheet", "columns": 8, "splitLayers": true}
  ]
}

Relative paths inside configuration files use the configuration file's directory, independently of the terminal's current directory. Paths supplied directly on the command line use the terminal's current directory. Output parent directories must already exist.

Previewing and running​

In your terminal, enter the directory containing build.json. Check the configuration and export plan, then run the export:

resprite-cli batch --config build.json --dry-run
resprite-cli batch --config build.json

A successful dry run creates no output. A successful actual run creates batch-hero.png, batch-hero-frames/manifest.json and batch-enemy-sheet/manifest.json. The latter two manifests list their image paths; see Reading exported assets.

Before running again, add "overwrite": true to each job whose output you want to replace. Image mode replaces a PNG. Frame sequences and sprite sheets can only update intact asset directories created by this CLI; see Replacement rules. Existing destinations also require explicit overwrite permission during a dry run.

For a single configuration job, save this separate example as one-job.json beside the project:

{
  "schemaVersion": 1,
  "jobs": [
    {"mode": "image", "source": "hero.resprite", "output": "hero-single.png", "frame": 0}
  ]
}
resprite-cli export --config one-job.json --dry-run
resprite-cli export --config one-job.json

export --config accepts exactly one job; use batch for multiple jobs. Configuration invocations allow only --dry-run as an additional option. Edit the JSON to change other options; command-line overrides are not accepted.

A dry run reads the project and checks arguments, output size budgets, paths and existing destinations. It does not render PNGs or create outputs or output locks, but still needs the runtime environment described in the platform guide. A successful dry run does not guarantee write permissions, enough disk space or a working renderer at execution time. Other processes may also occupy the destination later; the actual export checks again.

Results and errors​

When integrating through a process API, pass the executable path and argument array separately. For AppImage, the CLI argument array starts with --cli. 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.

For the complete exit-code table and output fields, see results and exit codes.

Single-job failures and errors before a batch starts leave stdout empty, with errors on stderr. Before starting, a batch checks all destinations: they must be distinct, must not contain each other, and must not replace or contain source projects or the configuration file. Linked paths and case aliases are checked too. No jobs run if these checks fail.

After these checks, jobs run serially in configuration order. Argument, input, output and rendering errors are recorded per job, and subsequent jobs continue. Internal errors abort immediately. Successful jobs retain their outputs; a batch failure does not roll back the whole batch.

A normally completed batch always returns a JSON summary. All jobs succeeding produces exit code 0; any failure, including all jobs failing, produces exit code 6. This excerpt shows the second of two image jobs failing; version, path and successful-image dimension fields are omitted:

{
  "action": "batch",
  "dryRun": false,
  "status": "error",
  "succeeded": 1,
  "failed": 1,
  "results": [
    {"index": 0, "exitCode": 0, "status": "ok"},
    {"index": 1, "exitCode": 4, "status": "error",
     "mode": "image", "code": "output_exists", "message": "Output exists; use --overwrite to replace it."}
  ]
}

index starts at 0 and follows the order of jobs. Failure details for exit code 6 appear in the stdout summary; reading only stderr misses them.

Each invocation has a 120-second limit covering all jobs in a batch. A timeout or forced termination may leave completed outputs without a final summary. Treat the process as failed, check the outputs, then retry with explicit overwrite permission where replacement is needed. Split large sets of jobs into smaller batches.