CLI Overview
The pxl command-line interface provides tools for working with Pixelsrc files. Commands fall into several categories:
Core Workflow
| 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 |
Authoring Tools
Inspection & Debugging
| Command | Description |
|---|---|
| show | Display sprites with colored terminal output |
| explain | Explain objects in human-readable format |
| diff | Compare sprites semantically |
| analyze | Extract corpus metrics from files |
AI Integration
| Command | Description |
|---|---|
| prime | Print format guide for AI context injection |
| prompts | Show GenAI prompt templates |
| suggest | Suggest fixes for common issues |
Reference Data
| Command | Description |
|---|---|
| palettes | List and inspect built-in palettes |
Global Behavior
File Formats
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.
Exit Codes
| 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.
Common Options
Many commands share common options:
--json- Output as JSON for scripting--strict- Treat warnings as errors--stdin- Read input from stdin
Quick Examples
# 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