Commands

pxw.py has 18 commands (swap is new in 0.8.0). Each prints one JSON object on stdout (indented two spaces), except review, which prints one line of JSON and then serves until stopped, and --version, which prints the version.

$ python pxw.py --help
usage: pxw.py [-h] [--version]
              {make,snap,bg,palette,clean,swap,crop,tile,palettes,frames,grid,mask,buildup,assemble,contact,pack,review,doctor} ...

pxw.py (pixelwright): real pixel art made from a render, and sprite animation
made in code from a still.

positional arguments:
  {make,snap,bg,palette,clean,swap,crop,tile,palettes,frames,grid,mask,buildup,assemble,contact,pack,review,doctor}

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
$ echo $?
0

Every command's JSON starts with ok, and a command that writes a file also prints out; the tables leave those two out. --help after a command lists its arguments, with no description of the command:

$ python pxw.py snap --help
usage: pxw.py snap [-h] [--scale SCALE] [--offset OFFSET] [--max MAX]
                   input out

positional arguments:
  input
  out

options:
  -h, --help       show this help message and exit
  --scale SCALE
  --offset OFFSET  X,Y of the first block edge, with --scale
  --max MAX
$ echo $?
0

Make commands

Command	Arguments and options	Prints
make	<recipe.json> <outdir> [--root DIR] (paths in the recipe are relative to it, default .) [--no-aw]	ok, id, out, preview, size, steps (each step's numbers), gates; for several sprites, ok and sprites
snap	<in> <out> [--scale S] [--offset X,Y] [--max 64]	scale, offset, native, uniform_blocks, detected, coherence (null when you gave the scale; left out when no grid was found)
bg	<in> <out> [--colour auto or R,G,B] [--tol 40] [--holes N] (since 0.8.0)	colour, cleared, enclosed_cleared (since 0.8.0), and note when the border was already transparent
palette	<in> <out> with exactly one of --palette P and --colours N; [--dither bayer2, bayer4 or bayer8] [--dither-space srgb or linear] [--max-step L] (both since 0.8.0) [--gpl OUT]	palette (hex), used, before
clean	<in> <out> [--alpha 128] [--orphans] [--thin] [--corners] (since 0.8.0) [--outline auto, selective or R,G,B] [--light top-left, top-right, top or none]	colours, and orphans_fixed, doubles_thinned, outlined, corners_fixed for the steps that ran
swap (since 0.8.0)	<in.png or folder> <out.png or folder> with --map map.json, or --from a.gpl --to b.gpl (any palette file)	out (a list), mapped, unmapped, note; exit 1 when a colour is unmapped
crop	<in> <out> [--pad 0] [--size pow2 or WxH] [--anchor bottom or centre]	sprite, canvas, at
tile	<in> <out> [--band N] (default a quarter of the shorter side)	seam_ratio_before, seam_ratio, new_colours
palettes	none	the built-in palettes and their sizes, and what else --palette takes

Examples of each: Making pixel art and Palettes.

Animation commands

Command	Arguments and options	Prints
frames	<brief.json> <outdir> [--root DIR] [--only NAME] [--no-aw]	ok, id, gates (the gates file), and per animation pass, frames, rest_frame_identical, changed_outside_mask, new_colours, noticeable, sheet
grid	<image> <out.png> [--zoom 8] [--step 8]	out, size, zoom
mask	<brief.json> <out.png> [--root DIR] [--zoom 4]	pixels_per_region, empty_regions
buildup	<brief.json> <out.json> [--anim place] [--frames 6]	anim, frames, buildup_frames
assemble	<brief.json> <out.json> --plan plan.json [--anim place] [--root DIR]	anim, frames, assemble_frames, uncovered_pixels, empty_parts, steps_ending_after_assembly
contact	<sheet.png> <out.png> --frames N [--per 5] [--zoom 3]	frames, frame_size
pack	<out.png> <frame.png>...	frames, frame_size
review	<dir> [--port 8765] [--extra items.json] [--print-page]	url, picks, then serves on 127.0.0.1

Examples of each: Animating a sprite.

Both

doctor takes nothing and prints version, python, numpy, pillow, missing, aw and effects (Getting started). --version prints the version alone.

Exit codes

Code	When	Stream
0	the command ran and every check held	JSON on stdout
1	a gate or check failed ("ok": false with the numbers), the command refused ("ok": false with an error), or an input file is missing or unreadable (since 0.6.2; 0.6.0 and 0.6.1 printed Python's traceback on stderr)	JSON on stdout
2	the argument parser refused the command line: its usage text	stderr
2	palette with both or neither of --palette and --colours; swap with neither --map nor both --from and --to (from the source; not run)	JSON on stdout

The program counted each stream for five of these cases:

python pxw.py: exit 2, stdout 0 lines, stderr 3 lines
python pxw.py palette cleared.png x.png --palette pico-8 --dither floyd: exit 2, stdout 0 lines, stderr 6 lines
python pxw.py palette cleared.png x.png --palette pico-8 --colours 6: exit 2, stdout 4 lines, stderr 0 lines
python pxw.py crop clean.png tiny.png --size 16x16: exit 1, stdout 4 lines, stderr 0 lines
python pxw.py snap nothing.png x.png: exit 1, stdout 4 lines, stderr 0 lines

A refusal:

$ python pxw.py crop clean.png tiny.png --size 16x16
{
  "ok": false,
  "error": "sprite is 20x19 (+0 pad); it does not fit 16x16"
}
$ echo $?
1

A missing input file:

$ python pxw.py snap nothing.png x.png
{
  "ok": false,
  "error": "FileNotFoundError: [Errno 2] No such file or directory: 'nothing.png'"
}
$ echo $?
1

No command at all:

$ python pxw.py
usage: pxw.py [-h] [--version]
              {make,snap,bg,palette,clean,swap,crop,tile,palettes,frames,grid,mask,buildup,assemble,contact,pack,review,doctor} ...
pxw.py: error: the following arguments are required: cmd
$ echo $?
2

Only snap was run with a missing file. From the source: frames and assemble name a still they cannot read as brief or still unreadable: ...; since 0.6.2 every other missing or unreadable file reaches the catch-all in main, which prints the error's type and message as above.

Every refusal the run printed

Command	Message
crop, make	sprite is 20x19 (+0 pad); it does not fit 16x16
palette	give exactly one of --palette and --colours (exit 2)
palette, make	palette not found: sweetie-16 (built-in: pico-8)
pack	frames differ in size: [(12, 12), (32, 32)]
swap	exit 1 with unmapped listing the colours the map left out (Making pixel art)
frames	use: unknown effect(s) ['wobble']; known: [...] (the list is every effect doctor names)
review	port 8799 is in use; stop the server on it or pick another port

The palette not found row for make comes from the source: make loads named palettes with the same function. Not run.