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. These guides describe CLI 0.3.0-prototype, included with Resprite 1.32.6 on macOS and Windows and also available in Linux x86_64 packages. --version reports the CLI version; check About for the application version.

Prepare your first export

1. Save a project as hero.resprite in your own project directory.
2. Open Help → Command-Line Tools in Resprite and copy a full command, or choose your platform below.
3. Replace the application and project paths with your actual paths. The output parent directory must already exist; hero.png should not exist on this first run.

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.

Run on your platform

macOS

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.

Windows

Windows x64 is available. Windows ARM64, RDP, disconnected sessions, service sessions and GPU-free CI have not been verified.

The executable is cli\resprite-cli.exe inside your installation directory. You can locate the installation from the Resprite shortcut. Run this example in PowerShell:

$cli = 'C:\Apps\Resprite\cli\resprite-cli.exe'
& $cli export image 'D:\Game Projects\hero.resprite' --output 'D:\Game Projects\hero.png' --frame 0
if ($LASTEXITCODE -ne 0) { throw "Resprite export failed: $LASTEXITCODE" }

Keep the complete installation directory, including the CLI's DLLs and data folder. Use & $cli --help or & $cli --version for help or the CLI version.

Using cmd batch files

"C:\Apps\Resprite\cli\resprite-cli.exe" export image "D:\Game Projects\hero.resprite" --output "D:\Game Projects\hero.png" --frame 0
if errorlevel 1 exit /b %errorlevel%

Linux

Linux x86_64 has been verified in local Ubuntu 22.04 graphics sessions with X11 (XWayland) and native Wayland. Other distributions and environments have not been verified. ARM64 packages and GPU-free CI are not supported. All commands, including --help and --version, require a usable graphics session.

AppDir: preserve symbolic links and executable permissions when extracting, and keep the complete distribution directory.

cli='/home/user/Apps/Resprite.AppDir/usr/bin/cli/resprite-cli'
"$cli" export image '/home/user/Game Projects/hero.resprite' \
  --output '/home/user/Game Projects/hero.png' --frame 0

Use "$cli" --help or "$cli" --version for help or the CLI version.

AppImage: use the original .AppImage file and put --cli first among application arguments. Replace the example filename with your actual package name.

cli='/home/user/Apps/Resprite.AppImage'
"$cli" --cli export image '/home/user/Game Projects/hero.resprite' \
  --output '/home/user/Game Projects/hero.png' --frame 0

Use "$cli" --cli --help or "$cli" --cli --version. Do not store AppImage's temporary mount path in scripts.

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

Installation does not add the CLI to PATH. Keep projects, outputs and custom scripts in your own project directory; installation contents may be replaced during upgrades or removed during uninstallation. If the application moves or is renamed, update your script paths or copy a fresh command from the help page.

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 as shorthand. In the terminal where you set $cli, replace it with:

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

• Image and animation export: export sequences and sheets, select clips, split layers and read animations.
• Configuration and batch exports: create reusable jobs, preview them and handle batch results.
• Command and format reference: look up parameters, JSON fields, exit codes and limits.

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.

macOS

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.

Windows

PowerShell 5.1's > re-encodes external program output. After decoding output correctly, use Out-File -Encoding utf8 to save UTF-8. With System.Diagnostics.Process, set StandardOutputEncoding to UTF-8.

Check the Windows installation

Run with the system's 64-bit Windows PowerShell 5.1, replacing the installation path:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File 'C:\Apps\Resprite\cli\verify_windows_installation.ps1'

The script uses bundled examples, needs no additional developer tools or dependency downloads, and does not modify installation files or your projects. It prints the report.json path and retains example exports. -CheckFilesOnly checks files without verifying an actual export.

Linux

For graphics_unavailable / exit code 70, run in an accessible X11 or Wayland graphics session. Set GDK_BACKEND=x11 or GDK_BACKEND=wayland only when that session is available. Retain stderr, which can include system loader diagnostics. Exports can also fail when the filesystem lacks required safe-write operations.

If AppImage reports missing FUSE, use extract-and-run mode:

"$cli" --appimage-extract-and-run --cli inspect '/home/user/Game Projects/hero.resprite'

Check the Linux installation

For a permanently extracted AppDir:

python3 '/home/user/Apps/Resprite.AppDir/usr/bin/cli/verify_linux_installation.py'

AppImage users can run "$cli" --appimage-extract in a temporary directory, then run python3 squashfs-root/usr/bin/cli/verify_linux_installation.py. The checker needs Python 3, Bash and bundled libraries, but no developer tools. It uses bundled examples without modifying installation files or your projects; reports and example exports remain at the printed location. --check-files-only works without a graphics session but does not verify actual exports.