Skip to main content
Complete reference for all command-line options available in Aseprite.

​
General Options

​
--batch or -b

Do not start the UI, run in batch mode. 
aseprite --batch input.ase --save-as output.png

​
--preview or -p

Do not execute actions, just print what will be done. 
aseprite --preview --batch input.ase --save-as output.png

​
--verbose or -v

Explain what is being done (verbose output). 
aseprite --verbose --batch input.ase --save-as output.png

​
--debug

Extreme verbose mode and copy log to desktop. 
aseprite --debug --batch input.ase --save-as output.png

​
--help or -?

Display help information and exit. 
aseprite --help

​
--version

Output version information and exit. 
aseprite --version

​
File Operations

​
--save-as <filename>

Save the last given sprite with a different format. 
aseprite --batch input.ase --save-as output.png
Supports filename templates: 
aseprite --batch *.ase --save-as converted/{title}.png

​
--palette <filename>

Change the palette of the last given sprite. 
aseprite --batch input.ase --palette custom.gpl --save-as output.png

​
--oneframe

Load just the first frame of animations. 
aseprite --batch animation.ase --oneframe --save-as first.png

​
Image Transformations

​
--scale <factor>

Resize all previously opened sprites by the given scale factor. 
aseprite --batch input.ase --scale 2 --save-as output.png

​
--shrink-to <width>,<height>

Shrink each sprite if it is larger than the specified dimensions. Maintains aspect ratio. 
aseprite --batch *.ase --shrink-to 128,128 --save-as {title}-small.png

​
--crop <x>,<y>,<width>,<height>

Crop all images to the specified rectangle. 
aseprite --batch input.ase --crop 10,10,64,64 --save-as cropped.png

​
--slice <name>

Crop the sprite to the given slice area. 
aseprite --batch input.ase --slice "character" --save-as character.png

​
--trim

Trim the whole sprite for --save-as or individual frames for --sheet. 
aseprite --batch input.ase --trim --save-as trimmed.png

​
--trim-sprite

Trim the whole sprite (for both --save-as and --sheet). 
aseprite --batch input.ase --trim-sprite --save-as trimmed.png

​
--trim-by-grid

Trim all images by their corresponding grid boundaries before exporting. 
aseprite --batch tileset.ase --trim-by-grid --save-as tiles.png

​
--extrude

Extrude all images by duplicating edge pixels one pixel outward. 
aseprite --batch animation.ase --extrude --sheet output.png --data output.json

​
Color Modes and Palettes

​
--color-mode <mode>

Change the color mode of all previously opened sprites. Modes:
  • rgb - RGB color mode
  • grayscale - Grayscale color mode
  • indexed - Indexed color mode (uses palette)
aseprite --batch input.ase --color-mode indexed --save-as output.png

​
--dithering-algorithm <algorithm>

Dithering algorithm used when converting from RGB to Indexed color mode. Algorithms:
  • none - No dithering
  • ordered - Ordered dithering (Bayer matrix)
  • old - Legacy dithering algorithm
  • error-diffusion - Error diffusion dithering
aseprite --batch rgb.ase \
  --dithering-algorithm ordered \
  --color-mode indexed \
  --save-as indexed.png

​
--dithering-matrix <id>

Matrix used for ordered dithering algorithm. Built-in matrices:
  • bayer2x2 - 2×2 Bayer matrix
  • bayer4x4 - 4×4 Bayer matrix
  • bayer8x8 - 8×8 Bayer matrix
  • filename.png - Custom matrix from PNG file
aseprite --batch input.ase \
  --dithering-algorithm ordered \
  --dithering-matrix bayer8x8 \
  --color-mode indexed \
  --save-as output.png

​
Layer Options

​
--layer <name> or --import-layer <name>

Include just the specified layer in the sheet or save operation. Can be used multiple times to include multiple layers: 
aseprite --batch input.ase --layer "Body" --layer "Head" --save-as output.png
Supports wildcards: 
aseprite --batch input.ase --layer "Group/*" --save-as output.png

​
--all-layers

Make all layers visible. By default, hidden layers are ignored. 
aseprite --batch input.ase --all-layers --save-as output.png

​
--ignore-layer <name>

Exclude the specified layer in the sheet or save operation. 
aseprite --batch input.ase --ignore-layer "Background" --save-as output.png

​
--split-layers

Save each visible layer as a separated file. 
aseprite --batch character.ase --split-layers --save-as {layer}.png
For sprite sheets: 
aseprite --batch character.ase \
  --split-layers \
  --sheet {layer}.png \
  --data {layer}.json

​
Animation and Tag Options

​
--tag <name> or --frame-tag <name>

Include only frames with the specified tag. 
aseprite --batch animation.ase --tag "walk" --save-as walk-{frame}.png

​
--play-subtags

Play subtags and repeats when saving frames of an animated sprite. 
aseprite --batch animation.ase --tag "main" --play-subtags --save-as {frame}.png

​
--split-tags

Save each tag as a separated file. 
aseprite --batch animations.ase --split-tags --save-as {tag}-{frame}.png
For sprite sheets: 
aseprite --batch animations.ase \
  --split-tags \
  --sheet {tag}.png \
  --data {tag}.json

​
--frame-range <from>,<to>

Export only frames in the specified range. 
aseprite --batch animation.ase --frame-range 0,10 --save-as frame-{frame}.png
When combined with --tag, the range is relative to the tag: 
aseprite --batch animation.ase --tag "walk" --frame-range 0,5 --save-as walk-{frame}.png

​
--ignore-empty

Do not export empty frames or cels. 
aseprite --batch animation.ase \
  --ignore-empty \
  --sheet output.png \
  --data output.json

​
Slice Options

​
--split-slices

Save each slice as a separated file. 
aseprite --batch tileset.ase --split-slices --save-as slice-{slice}.png

​
Grid Options

​
--split-grid

Save each grid tile as a separated file. 
aseprite --batch tileset.ase --split-grid --save-as tile-{frame}.png

​
Sprite Sheet Options

​
--sheet <filename>

Image file to save the sprite sheet texture. 
aseprite --batch animation.ase --sheet output.png --data output.json

​
--data <filename>

JSON file to store the sprite sheet metadata. 
aseprite --batch animation.ase --sheet output.png --data output.json

​
--sheet-type <type>

Algorithm to create the sprite sheet. Types:
  • horizontal - Single horizontal row
  • vertical - Single vertical column
  • rows - Multiple rows (use with --sheet-columns)
  • columns - Multiple columns (use with --sheet-rows)
  • packed - Bin-packing algorithm
aseprite --batch animation.ase \
  --sheet-type packed \
  --sheet output.png \
  --data output.json

​
--sheet-pack

Shorthand for --sheet-type packed. 
aseprite --batch animation.ase \
  --sheet-pack \
  --sheet output.png \
  --data output.json

​
--sheet-width <pixels>

Fixed width for the sprite sheet. 
aseprite --batch animation.ase \
  --sheet-width 1024 \
  --sheet output.png \
  --data output.json

​
--sheet-height <pixels>

Fixed height for the sprite sheet. 
aseprite --batch animation.ase \
  --sheet-height 1024 \
  --sheet output.png \
  --data output.json

​
--sheet-columns <columns>

Fixed number of columns for --sheet-type rows. 
aseprite --batch animation.ase \
  --sheet-type rows \
  --sheet-columns 8 \
  --sheet output.png \
  --data output.json

​
--sheet-rows <rows>

Fixed number of rows for --sheet-type columns. 
aseprite --batch animation.ase \
  --sheet-type columns \
  --sheet-rows 8 \
  --sheet output.png \
  --data output.json

​
--format <format>

Format to export the data file. Formats:
  • json-hash - JSON object with frame names as keys (default)
  • json-array - JSON array of frames
aseprite --batch animation.ase \
  --format json-array \
  --sheet output.png \
  --data output.json

​
--merge-duplicates

Merge all duplicate frames into one in the sprite sheet. 
aseprite --batch animation.ase \
  --merge-duplicates \
  --sheet output.png \
  --data output.json

​
--border-padding <value>

Add padding on the texture borders. 
aseprite --batch animation.ase \
  --border-padding 4 \
  --sheet output.png \
  --data output.json

​
--shape-padding <value>

Add padding between frames. 
aseprite --batch animation.ase \
  --shape-padding 2 \
  --sheet output.png \
  --data output.json

​
--inner-padding <value>

Add padding inside each frame. 
aseprite --batch animation.ase \
  --inner-padding 1 \
  --sheet output.png \
  --data output.json

​
Tileset Options

​
--export-tileset

Export only tilesets from visible tilemap layers. 
aseprite --batch tilemap.ase \
  --export-tileset \
  --sheet tileset.png \
  --data tileset.json

​
Metadata Options

​
--list-layers

List layers of the next given sprite or include layers in JSON data. 
aseprite --batch input.ase --list-layers
With sprite sheet: 
aseprite --batch input.ase \
  --list-layers \
  --sheet output.png \
  --data output.json

​
--list-layer-hierarchy

List layers with groups or include layer hierarchy in JSON data. 
aseprite --batch input.ase --list-layer-hierarchy

​
--list-tags

List tags of the next given sprite or include frame tags in JSON data. 
aseprite --batch animation.ase --list-tags
With sprite sheet: 
aseprite --batch animation.ase \
  --list-tags \
  --sheet output.png \
  --data output.json

​
--list-slices

List slices of the next given sprite or include slices in JSON data. 
aseprite --batch tileset.ase --list-slices

​
Filename Templates

​
--filename-format <format>

Special format to generate filenames. Available variables:
  • {title} - File title (without extension)
  • {frame} - Frame number
  • {tag} - Tag name
  • {layer} - Layer name
  • {group} - Group name
  • {slice} - Slice name
aseprite --batch animation.ase \
  --filename-format "{title}-{tag}-{frame}" \
  --sheet output.png \
  --data output.json

​
--tagname-format <format>

Special format to generate tag names in JSON data. 
aseprite --batch animation.ase \
  --tagname-format "{title}_{tag}" \
  --sheet output.png \
  --data output.json

​
Scripting Options

​
--shell

Start an interactive console to execute scripts. 
aseprite --shell

​
--script <filename>

Execute a specific Lua script. 
aseprite --batch input.ase --script process.lua --save-as output.png

​
--script-param <name>=<value>

Pass parameters to scripts executed from the CLI. Access in scripts via app.params: 
aseprite --batch input.ase \
  --script process.lua \
  --script-param mode=export \
  --script-param quality=high \
  --save-as output.png
In the Lua script: 
local mode = app.params["mode"]  -- "export"
local quality = app.params["quality"]  -- "high"

​
Platform-Specific Options

​
--disable-wintab (Windows only)

Don’t load the wintab32.dll library. 
aseprite --disable-wintab

​
--noinapp (Steam version only)

Disable “in game” visibility on Steam. Doesn’t count playtime. 
aseprite --noinapp

​
Usage Patterns

​
Option Order

Options are processed in the order they appear. This matters for operations that depend on previous commands: 
# Correct: Load file, then scale it, then save
aseprite --batch input.ase --scale 2 --save-as output.png

# Wrong: Scale happens before file is loaded
aseprite --batch --scale 2 input.ase --save-as output.png

​
Multiple Files

Process multiple files in one command: 
aseprite --batch file1.ase file2.ase file3.ase --scale 2 --save-as {title}-2x.png

​
Wildcards

Use shell wildcards to match multiple files: 
aseprite --batch *.ase --save-as converted/{title}.png

​
Combining Options

Options can be combined for complex operations: 
aseprite --batch animation.ase \
  --scale 2 \
  --color-mode indexed \
  --dithering-algorithm ordered \
  --dithering-matrix bayer4x4 \
  --trim \
  --ignore-layer "Background" \
  --tag "walk" \
  --frame-range 0,7 \
  --sheet-pack \
  --shape-padding 2 \
  --border-padding 4 \
  --ignore-empty \
  --merge-duplicates \
  --list-tags \
  --format json-hash \
  --sheet output.png \
  --data output.json