Docs · Command line
LibreSprite command line: batch export and automation
Everything you export by hand can also run from a terminal or a build script: GIFs, PNG frames, sprite sheets with JSON, scaled copies, and your own scripts. We ran every option below on LibreSprite 1.3 and noted where it behaves unexpectedly.
On this page 7 sections
Short answer
How do I export from LibreSprite on the command line?
Add -b (batch: no window) and give the file, then what to write: libresprite -b walk.ase --save-as walk.gif for a GIF, or libresprite -b walk.ase --sheet walk.png --data walk.json for a sprite sheet with JSON. Options apply to the files that come after them, so layer and sheet options go before the file name.
CLI Builder
Pick what you want; the command updates as you go. It uses the option order and workarounds from our tests.
Recipes we tested
# Horizontal strip + JSON (frames keyed by name), with layers and tags in meta
libresprite -b --list-layers --list-tags walk.ase --sheet walk.png --data walk.json --format json-hash
# Vertical strip: use "columns" (in 1.3 "vertical" makes a horizontal strip)
libresprite -b walk.ase --sheet walk.png --sheet-type columns
# Only the frames of one tag, trimmed, 2 px apart
libresprite -b --frame-tag walk --trim --shape-padding 2 hero.ase --sheet walk.png --data walk.json --format json-array
# One row per layer
libresprite -b --split-layers hero.ase --sheet layers.pnglibresprite -b walk.ase --save-as walk.gif # animated GIF, durations kept
libresprite -b walk.ase --scale 4 --save-as walk-x4.gif # 4× bigger, crisp (nearest-neighbour)
libresprite -b walk.ase --save-as frame.png # frame1.png, frame2.png …
libresprite -b walk.ase --filename-format "{title}-{layer}-{frame}.{extension}" --split-layers --save-as split.png
libresprite -b big.ase --shrink-to 64,64 --save-as small.pnglibresprite -b --list-layers --list-tags walk.ase # prints layer names, then tag names
libresprite -b walk.ase --script outline.js --save-as out.gif
libresprite --version # LibreSprite 1.3Things that surprised us in 1.3
| What you’d expect | What 1.3 does | Do this |
|---|---|---|
sprite.ase --list-layers lists layers | Prints nothing: options only affect files after them | Put options before the file |
--sheet-type vertical makes a vertical strip | Makes a horizontal strip (128 × 32 from our 4 frames) | Use --sheet-type columns |
--save-as frame-{frame}.png numbers the files | Writes frame-1{frame0}.png… | Use --filename-format |
| A name ending in a number is kept as is | --save-as shrink-16.png wrote shrink-16.png … shrink-19.png (treated as a sequence start) | Avoid trailing numbers in names |
| Tags appear in the JSON | Only with --list-tags (and layers with --list-layers) | Add both flags |
--scale 4 updates meta.scale | Frames are scaled, meta.scale stays "1" | Ignore meta.scale |
| JSON goes to a file | Without --data, it is printed to the terminal | Always add --data |
| Saving FLC/FLI works | Fails for RGB sprites (“Error saving file: Cannot open”) | Convert to Indexed in the app first |
All options
The output of libresprite --help in 1.3. LibreSprite’s development branch adds --set key=value (pass values to a --script run); it is not in the 1.3 release.
| Option | What it does (from --help) |
|---|---|
--palette <filename> | Use a specific palette by default |
--shell | Start an interactive console to execute scripts |
-b, --batch | Do not start the UI |
--save-as <filename> | Save the last given document with other format |
--scale <factor> | Resize all previous opened documents |
--shrink-to | width,height Shrink each sprite if it is larger than width or height |
--data <filename.json> | File to store the sprite sheet metadata |
--format <format> | Format to export the data file (json-hash, json-array) |
--sheet <filename.png> | Image file to save the texture |
--sheet-width <pixels> | Sprite sheet width |
--sheet-height <pixels> | Sprite sheet height |
--sheet-type <type> | Algorithm to create the sprite sheet: horizontal vertical rows columns packed |
--sheet-pack | Same as --sheet-type packed |
--split-layers | Import each layer of the next given sprite as a separated image in the sheet |
--layer <name> | Include just the given layer in the sheet (alias --import-layer) |
--import-layer <name> | Include just the given layer in the sheet |
--all-layers | Make all layers visible By default hidden layers will be ignored |
--frame-tag <name> | Include tagged frames in the sheet |
--frame-range | from,to Only export frames in the [from,to] range |
--ignore-empty | Do not export empty frames/cels |
--border-padding <value> | Add padding on the texture borders |
--shape-padding <value> | Add padding between frames |
--inner-padding <value> | Add padding inside each frame |
--trim | Trim all images before exporting |
--crop | x,y,width,height Crop all the images to the given rectangle |
--filename-format <fmt> | Special format to generate filenames |
--script <filename> | Execute a specific script |
--list-layers | List layers of the next given sprite or include layers in JSON data |
--list-tags | List tags of the next given sprite sprite or include frame tags in JSON data |
-v, --verbose | Explain what is being done |
--debug | Extreme verbose mode and copy log to desktop |
--version | Output version information and exit |
Where the program is
| Windows (installer) | "C:\Program Files\LibreSprite\libresprite.exe" (in PowerShell, start the line with &). --version printed LibreSprite 1.3 in our test. |
|---|---|
| Windows (zip) | libresprite.exe in the folder you extracted |
| macOS | /Applications/libresprite.app/Contents/MacOS/libresprite (we ran --version and a sprite-sheet export with it on macOS 15) |
| Linux | The AppImage itself (./libresprite-v1.3-linux-x86_64.AppImage -b …), libresprite for distribution packages, or flatpak run com.github.libresprite.LibreSprite |
Use it in a build pipeline
Export art automatically whenever it changes, so a game always gets fresh sprite sheets:
SPRITES := $(wildcard art/*.ase)
SHEETS := $(SPRITES:art/%.ase=assets/%.png)
assets/%.png: art/%.ase
libresprite -b --list-tags $< --sheet $@ --data $(@:.png=.json) --format json-hash
all: $(SHEETS)- name: Export sprites with LibreSprite
run: |
curl -sSLo ls.AppImage https://github.com/LibreSprite/LibreSprite/releases/download/v1.3/libresprite-v1.3-linux-x86_64.AppImage
chmod +x ls.AppImage && ./ls.AppImage --appimage-extract > /dev/null
for f in art/*.ase; do
./squashfs-root/AppRun -b --list-tags "$f" --sheet "assets/$(basename "$f" .ase).png" --data "assets/$(basename "$f" .ase).json" --format json-hash
doneExtracting the AppImage (--appimage-extract) avoids needing FUSE on CI machines; that is how we ran all our Linux tests.
FAQ
Does the command line open a window?
Not with -b (--batch). Without it, LibreSprite opens normally after processing the options.
Can I convert a whole folder at once?
Yes, with a loop in your shell: for f in *.ase; do libresprite -b "$f" --save-as "${f%.ase}.gif"; done (Linux/macOS) or Get-ChildItem *.ase | % { & libresprite.exe -b $_.Name --save-as ($_.BaseName + ".gif") } (PowerShell).
Is the JSON compatible with Aseprite’s?
It follows the same hash and array layouts that engines’ Aseprite importers read, but lacks Aseprite’s newer fields (slices, tag repeat). See the JSON file.
Can I change the frame duration from the command line?
No option for that in 1.3; set durations in the app (Frame → Frame Properties).
Keep going
Found something wrong or out of date? Tell us: hello@libresprite.dev. We fix mistakes within a day.