Skip to main content
Aseprite’s CLI allows you to batch process multiple files, applying transformations and conversions efficiently.

​
Basic Batch Conversion

The simplest form of batch conversion is to convert a single file to another format: 
aseprite --batch input.ase --save-as output.png

​
Processing Multiple Files

You can process multiple files in a single command: 
aseprite --batch file1.ase file2.ase file3.ase --save-as {title}.png
This will create:
  • file1.png
  • file2.png
  • file3.png

​
Filename Templates

Use template variables in the output filename to customize the naming: 
aseprite --batch *.ase --save-as converted/{title}-{frame}.png

​
Available Template Variables

  • {title} - File title (without extension)
  • {frame} - Frame number
  • {tag} - Tag name
  • {layer} - Layer name
  • {group} - Group name
  • {slice} - Slice name

​
Scaling Sprites

Resize sprites during conversion: 
# Scale by factor
aseprite --batch input.ase --scale 2 --save-as output.png

# Scale to maximum dimensions (maintains aspect ratio)
aseprite --batch *.ase --shrink-to 128,128 --save-as {title}-small.png

​
Color Mode Conversion

Convert between different color modes: 
# Convert to RGB
aseprite --batch indexed.ase --color-mode rgb --save-as rgb.png

# Convert to Grayscale
aseprite --batch color.ase --color-mode grayscale --save-as gray.png

# Convert to Indexed with dithering
aseprite --batch rgb.ase \
  --color-mode indexed \
  --dithering-algorithm ordered \
  --dithering-matrix bayer8x8 \
  --save-as indexed.png

​
Dithering Algorithms

When converting to indexed color mode:
  • none - No dithering
  • ordered - Ordered dithering (requires matrix)
  • old - Legacy dithering algorithm
  • error-diffusion - Error diffusion dithering

​
Dithering Matrices

For ordered dithering:
  • bayer2x2 - 2×2 Bayer matrix
  • bayer4x4 - 4×4 Bayer matrix
  • bayer8x8 - 8×8 Bayer matrix
  • filename.png - Custom matrix from PNG file

​
Palette Management

Change the palette of sprites: 
aseprite --batch input.ase --palette custom-palette.ase --save-as output.png

​
Cropping and Trimming

​
Crop to Specific Rectangle

aseprite --batch input.ase --crop 10,10,64,64 --save-as cropped.png
Format: --crop x,y,width,height

​
Trim Transparent Pixels

# Trim the entire sprite
aseprite --batch input.ase --trim --save-as trimmed.png

# Trim by grid boundaries
aseprite --batch input.ase --trim-by-grid --save-as trimmed.png

​
Crop to Slice

aseprite --batch input.ase --slice "character" --save-as character.png

​
Layer Filtering

​
Export Specific Layers

# Export only a specific layer
aseprite --batch input.ase --layer "Background" --save-as bg.png

# Export multiple layers
aseprite --batch input.ase --layer "Layer1" --layer "Layer2" --save-as output.png

​
Ignore Layers

aseprite --batch input.ase --ignore-layer "Draft" --save-as final.png

​
Make All Layers Visible

aseprite --batch input.ase --all-layers --save-as all-layers.png

​
Layer Wildcards

Use wildcards for layer matching: 
# Match all layers in a group
aseprite --batch input.ase --layer "Group/*" --save-as grouped.png

​
Tag-Based Export

Export specific animation tags: 
# Export specific tag
aseprite --batch animation.ase --tag "walk" --save-as walk-{frame}.png

# Play subtags when exporting
aseprite --batch animation.ase --tag "main" --play-subtags --save-as anim-{frame}.png

​
Frame Range Export

Export only specific frames: 
# Export frames 0 to 9
aseprite --batch animation.ase --frame-range 0,9 --save-as frame-{frame}.png

# Export frame range within a tag
aseprite --batch animation.ase --tag "walk" --frame-range 0,5 --save-as walk-{frame}.png

​
Automatic Template Detection

When you use templates in the filename, Aseprite automatically enables splitting: 
# Automatically splits layers because {layer} is used
aseprite --batch input.ase --save-as output-{layer}.png

# Automatically splits tags because {tag} is used
aseprite --batch animation.ase --save-as anim-{tag}-{frame}.png

​
Advanced Examples

​
Convert all ASE files to PNG with scaling

aseprite --batch *.ase --scale 2 --save-as converted/{title}.png

​
Export only visible layers from multiple files

aseprite --batch *.ase --ignore-layer "Draft" --save-as final/{title}.png

​
Convert to indexed color with custom palette

aseprite --batch *.ase \
  --palette my-palette.gpl \
  --color-mode indexed \
  --dithering-algorithm ordered \
  --dithering-matrix bayer4x4 \
  --save-as indexed/{title}.png

​
Process and trim sprites

aseprite --batch *.ase --trim --save-as trimmed/{title}.png

​
Loading Options

​
Load Only First Frame

For faster processing when you only need the first frame: 
aseprite --batch animation.ase --oneframe --save-as first-frame.png

​
Scripting Integration

Execute Lua scripts during batch processing: 
# Run a script on files
aseprite --batch input.ase --script process.lua --save-as output.png

# Pass parameters to the script
aseprite --batch input.ase \
  --script process.lua \
  --script-param mode=export \
  --script-param quality=high \
  --save-as output.png
In your Lua script, access parameters via app.params: 
local mode = app.params["mode"]  -- "export"
local quality = app.params["quality"]  -- "high"

​
Error Handling

Aseprite will:
  • Print error messages to stderr
  • Return a non-zero exit code on failure
  • Continue processing other files if one fails (when processing multiple files)
Use --verbose or --debug flags to get more information about errors: 
aseprite --batch --verbose input.ase --save-as output.png