CLI guide

Use the command line to build an input folder or a saved .packrat project.

packrat build assets --format json-hash --output out/atlas
packrat build game.packrat --watch
packrat validate game.packrat --strict --json-summary
packrat build game.packrat --scale 1 --scale 2

Commands

Command	What it does
build <folder/project>...	Pack frames and write the exported files
validate <folder/project>...	Scan sources and test packing without writing exports
list-assets <folder/project>...	List enabled entries, including labelled effect sources
inspect <folder/project>...	Show the settings and asset counts that will be used
list-formats	List export formats and their option values
--version / --help	Print the version or help; use build --help for build flags

A project supplies its saved settings and effect overrides. CLI flags override those settings. You can pass several projects with distinct output paths; Packrat runs up to four at a time.

--watch accepts one project. For a batch, --json-summary writes one JSON object per project. JSON summaries support one scale and cannot be combined with watch mode.

Options

Setting	Flags
Inputs	--project <file> and --input <folder>; both can be repeated
Filters	--include <path-or-pattern>, --exclude <path-or-pattern>
Destination	--output <base-path>, or --output-dir <dir> --name <stem>
Formats	--format <name>, --image-format png|bmp|tga
Encoding	--quality fast|balanced|small
Pages	--max-size <pixels>, --split / --no-split, --power-of-two / --no-pot
Packing	--algorithm maxrects|skyline|shelf|grid, --padding <pixels>, --border <pixels>
Trimming	--trim-mode none|trim|crop-keep-position|crop, --trim-margin <pixels>, --trim-threshold <alpha>, --extrude <pixels>
Scale	--scale <factor>; repeat for several sizes; default is 1
Validation	--strict fails on source issues; --pack-only / --check tests packing without export
Logging	--quiet, --verbose, --profile, --json-summary
Rebuild	--force bypasses saved build caches; --clean also removes stale files from earlier exports with the same output base path
Watch for changes	--watch

Filters match the logical paths used for exported names. They accept * and ? wildcards and can exclude additional files. They cannot re-enable entries ignored in the project. Include companion image paths when filtering manual effects.

Scale must be a finite value greater than 0 and no larger than 100. Rotated packing is disabled: --rotation fails, and --no-rotation overrides a saved project that requested rotation.

validate, --check, and --pack-only test the base packing layout. Run a full build to check effect generation and companion image dimensions.

Scale and effects

Repeat --scale to export several sizes. For example, scales of 1 and 2 use the base filenames atlas@1x and atlas@2x. A single scale of 1 keeps the base name atlas. Scaling uses nearest-neighbor sampling and also scales the spacing between frames.

To export glow or normal maps, enable them in the GUI and save the project before building it from the CLI. See Output files for page and effect filenames.

Cache and watch

Packrat stores its build cache in .packrat_cache beside the executable. It can reuse unchanged exports without packing again, and reuse prepared sprites when a new layout is needed. It checks file contents, so it detects edits to sources, companions, and exported files even when their sizes and timestamps are unchanged.

Missing or corrupt cache files cause a rebuild. Builds with source issues are checked again. You can delete the cache; Packrat will recreate it when needed.

Use --force to rebuild without reusing saved cache data. Use --clean to rebuild and then remove stale files from earlier exports. Strict, JSON-summary, check-only, and watch builds bypass the saved build cache.

--watch exports again when the operating system reports a source change. It filters generated output and temporary files to avoid triggering itself. Watch mode rejects --scale and check-only flags.

See Sources and outputs for supported files, trim modes, effects, and limits.