The pxl command-line interface provides tools for working with Pixelsrc files. Commands fall into several categories:
Command Description
render Render sprites to PNG, GIF, or atlas formats import Convert PNG images to Pixelsrc format validate Check files for errors and common mistakes fmt Format files for consistent style build Build all assets according to pxl.toml
Command Description
new Create new assets from templates init Initialize a new Pixelsrc project sketch Create sprites from simple text grids
Command Description
show Display sprites with colored terminal output grid Display grid with row/column coordinates inline Expand grid with column-aligned spacing explain Explain objects in human-readable format diff Compare sprites semantically analyze Extract corpus metrics from files
Command Description
prime Print format guide for AI context injection prompts Show GenAI prompt templates suggest Suggest fixes for common issues alias Extract repeated patterns into aliases
Command Description
palettes List and inspect built-in palettes
The CLI supports two file formats:
.pxl - Human-readable Pixelsrc format.jsonl - JSON Lines format (legacy, still supported)
Both formats can contain palettes, sprites, animations, compositions, and other objects.
Code Meaning
0 Success 1 General error (invalid input, missing file, etc.) 2 Validation failed (with --strict mode)
See Exit Codes for the complete list.
Many commands share common options:
--json - Output as JSON for scripting--strict - Treat warnings as errors--stdin - Read input from stdin
# Render a sprite to PNG
pxl render sprite.pxl -o output.png
# Validate all files in a directory
pxl validate *.pxl
# Format files in place
pxl fmt *.pxl
# Preview a sprite in terminal
pxl show sprite.pxl
# Build a project
pxl build
# Get AI context for sprite generation
pxl prime --brief