CLI guide

The CLI can be used from a built executable, for example:

zig-out\bin\packrat.exe build assets --format libgdx --output-dir build\atlas --name game

When working from the repository, zig build run -- passes arguments to the same CLI:

zig build run -- build assets --format json-hash --output-dir build\atlas --name game

Commands

build <folder>... [project.packrat]
list-assets <folder>... [project.packrat]
inspect <folder>... [project.packrat]
validate <folder>... [project.packrat]
convert <input> [output]
list-formats

build packs source images and writes output files. list-assets reports discovered entries; inspect reports resolved settings and counts; validate packs without exporting. convert converts one PNG, BMP, TGA, ASE, or Aseprite source.

Useful examples

# Use saved settings, but override the destination.
packrat build game.packrat --output-dir build\atlas --name game

# Pack several folders with filters.
packrat build assets\ui assets\effects --include "ui/*" --exclude "*/debug*"

# Validate in CI without writing files.
packrat validate game.packrat --strict --json-summary

# Rebuild continuously while editing source images.
packrat build game.packrat --watch

# Convert a source image to another supported image format.
packrat convert source.png --image-format tga --quality fast

Important options

--format selects the data exporter. --image-format accepts png, bmp, or tga; PNG is the safest choice for engine integrations. --output, --output-dir, and --name override the project destination. --input adds folders, while --include and --exclude filter logical asset paths.

Packing overrides include --max-size, --padding, --border, --algorithm skyline|maxrects|shelf|grid, --trim-mode none|trim|crop-keep-position|crop, --trim-margin, --trim-threshold, --extrude, --power-of-two, and --no-pot.

Use --clean after a successful export to remove stale outputs for the selected format. Use --json-summary for automation, --strict to fail on source issues, and --quiet or --verbose to control logging.