CLI guide

The CLI can be used from the Packrat executable:

packrat build assets --format libgdx --output-dir build/atlas --name game

Commands

build <folder>... [project.packrat ...]
list-assets <folder>... [project.packrat ...]
inspect <folder>... [project.packrat ...]
validate <folder>... [project.packrat ...]
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.

Multiple project files can be passed in one invocation. They are processed in parallel, up to four projects at a time:

packrat build game.packrat ui.packrat effects.packrat
packrat validate game.packrat --project ui.packrat

All command-line overrides apply to every project. For builds, each project must resolve to a different output path. --watch is currently available only when one project is selected. Normal output from parallel projects may be interleaved; use --quiet for automation. With --json-summary, multiple projects emit one compact JSON summary object per line.

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

Important options

--format selects the data exporter. --image-format accepts png, bmp, or tga; choose the image format supported by your target engine. --output, --output-dir, and --name override the project destination. --project may be repeated to select multiple project files. --input adds folders, while --include and --exclude filter logical asset paths.

Packing overrides include --max-size, --padding, --border, --algorithm skyline|maxrects|shelf|grid (default: maxrects), --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. --profile prints a hierarchical timing report to stderr, including packer internals. Successful builds are recorded beside the executable in .packrat_cache; unchanged builds skip packing and export. The same cache also keeps prepared sprites so a later build that does need to repack can reuse decoded, scaled, and trimmed source data. Use --force to bypass the no-change skip; it still allows prepared sprites to be reused. Cache files are disposable and are rebuilt automatically if removed or invalidated.