Skip to main content

CLI Quick Start

Resprite CLI exports saved .resprite projects as single PNG images, frame sequences or regular sprite sheets. It also supports project inspection, JSON configuration and batch exports for project build workflows.

The CLI is experimental and is included with Resprite on macOS, Windows, and Linux x86_64. --version reports the CLI version; check About for the application version.

Set up the terminal command​

Open Help ▸ Command-Line Tools ▸ Add to PATH, then close and reopen your terminal application. Registration applies to the current user. You can then run resprite-cli without writing the application path.

  • macOS / Linux: automatic setup supports Bash, Zsh, and Fish.
  • Windows: setup adds the installation's cli directory to the user PATH, preserving existing entries. Administrator rights are not required. If a new terminal still has the old PATH, sign out and back in.
  • Linux AppImage: registration calls the original AppImage and supplies --cli automatically. Keep the AppImage at a stable location.

If you prefer not to register PATH, use the direct invocation examples instead.

Prepare your first export​

  1. Save a project as hero.resprite in your own project directory.
  2. After setting up PATH, open a new terminal in that directory. You can also copy a complete command from Help ▸ Command-Line Tools.
  3. Check that the output parent directory exists and that hero.png does not exist on the first run, then run:
resprite-cli export image "hero.resprite" --output "hero.png" --frame 0

With these relative paths, hero.png is written beside the source project. For invocation without PATH registration, use your platform's full-path example below.

The CLI reads only saved content on disk. It does not change the source project or the editor's document, frame, or selection. Frame indices start at 0. All platforms require a usable graphics environment, although no editor window appears during execution.

Direct invocation by platform​

Packages include Apple Silicon (arm64) and Intel (x86_64) architectures. Compatibility with specific macOS versions and hardware still needs confirmation. GPU-free CI and non-interactive service sessions have not been verified.

cli='/Applications/Resprite.app/Contents/MacOS/resprite-cli'
"$cli" export image "$HOME/Game Projects/hero.resprite" \
  --output "$HOME/Game Projects/hero.png" --frame 0

Keep the complete .app; copying only the executable is insufficient. Use "$cli" --help to view syntax or "$cli" --version to check the CLI version.

On success, find hero.png beside your source project. It composites visible layers and preserves transparency. The terminal also prints a JSON result. To replace the PNG on a later run, append --overwrite to the export command. Animation directories have different replacement rules.

Paths and further examples​

After moving or renaming the application, return to Help ▸ Command-Line Tools ▸ Repair Registration. Before uninstalling or switching installations, use Remove Registration. Registration does not overwrite conflicting commands or another usable installation; removal only cleans up entries created by this feature. Manually configured PATH entries remain yours to manage.

Keep projects, outputs, and custom scripts in your own project directory. Installation contents may be replaced during upgrades or removed during uninstallation. When using full paths, update script paths after the application moves.

Command-line relative paths use the terminal's current directory. Relative paths inside JSON configurations use the configuration file's directory. Quote paths containing spaces.

The other guides use resprite-cli directly once PATH registration is complete. If you instead set $cli using a full-path example, replace resprite-cli as follows:

PlatformInvocation
macOS / Linux AppDir"$cli" ...
Windows PowerShell& $cli ...
Linux AppImage"$cli" --cli ...

The help page also opens the bundled platform, animation and workflow guides for offline reading. Use Show in Folder to locate the Markdown files and choose a reader.

Troubleshooting​

If no image appears, check the exit code and stderr, then verify that the source is saved, the output parent exists and is writable, and replacement is explicitly allowed when needed. Linked output paths are rejected; file locks and permissions can also prevent export. See results and exit codes.

Each invocation has a 120-second limit, including all batch jobs. After a timeout or forced termination, check for completed outputs before retrying. Temporary resprite_cli_* directories or .resprite_cli_* entries in the output parent may remain. Do not delete lock files or clean related directories until all CLI jobs have stopped.

If macOS blocks startup, retain the system message and contact support. The installation checker cannot grant launch permission or remove system restrictions.

Check the macOS installation
/bin/bash '/Applications/Resprite.app/Contents/Helpers/RespriteCLI.app/Contents/Resources/verify_macos_installation.sh'

Replace the installation path as needed. The script uses macOS tools and bundled examples; no additional developer tools are required. It does not modify installation files or your projects. It prints the report.txt path and retains example exports and stdout/stderr for support.