中文文档： README.zh-CN.md
Headless pixel art engine for scripts, pipelines, and AI agents.
Create, edit, and export.piskelfiles from the terminal; useservewhen you want the bundled Piskel web editor in a browser.
Piskel is a beloved browser-based pixel art editor. piskel-cli brings its .piskel format to the command line, making pixel art a first-class citizen in any automated workflow:
- AI agents can generate sprites and animations with a single prompt — no image model required
- Build pipelines can produce and export assets without human interaction
- Scripts can batch-edit hundreds of frames in seconds
- CI/CD can validate and regenerate pixel art assets automatically
Every operation is scriptable, composable, and returns structured JSON — trivially easy to chain with other tools.
You don't need an image generation model to create pixel art with AI. Any LLM that can write JSON can generate production-ready sprites and animations by describing them as a plan file.
npx skills add Ne9roni/piskel-cliThis installs a structured prompt (skills/piskel-skill/SKILL.md) into your AI agent that teaches it the full piskel-cli workflow — including a mandatory alignment step before making any changes, so the AI never generates something you didn't ask for.
Tell your AI agent (Claude, GPT, Cursor, etc.) what you want in plain language:
"Draw a 16×16 red mushroom sprite with white spots and export it as PNG"
The agent writes a plan.json and runs:
piskel-cli run mushroom-plan.json --jsonThat's it. No image model. No diffusion. Pure geometry.
Everything below was generated entirely by an AI agent using piskel-cli — from a one-line description to exported files. No image model was involved.
| Mushroom | Gem | Sword | Heart |
|---|---|---|---|
 |
 |
 |
 |
| mushroom-plan.json | gem-plan.json | sword-plan.json | heart-plan.json |
| Coin Spin | Fire | Ghost | Twinkle Star |
|---|---|---|---|
 |
 |
 |
 |
| coin-spin-plan.json | fire-plan.json | ghost-plan.json | twinkle-star-plan.json |
Each example is a self-contained JSON plan file in examples/. Run any of them yourself:
piskel-cli run examples/fire-plan.json --json# Install globally (recommended)
npm install -g @ne9roni/piskel-cli
# Verify
piskel-cli --helpThe published npm package includes a production build of Piskel under vendor/piskel-prod, so npm install -g @ne9roni/piskel-cli is enough for piskel-cli serve — no separate clone or download of the editor.
Or use locally from source:
git clone https://github.com/Ne9roni/piskel-cli.git
cd piskel-cli
npm install && npm run build
node dist/src/cli.js --helpIf you clone without vendor/piskel-prod, run npm run sync-piskel-vendor once (needs a built piskel tree; see vendor/README.md).
Optional: open the same pixel editor as piskelapp.com on your machine:
piskel-cli serve
piskel-cli serve path/to/project.piskelUse --no-open to only print the URL, and --port / --host to control the local server. Press Ctrl+C to stop.
piskel-cli project create --width 16 --height 16 --name my-sprite --jsonpiskel-cli draw rect output/my-sprite.piskel --x1 2 --y1 2 --x2 13 --y2 13 --color "#ff0000" --filled --json
piskel-cli draw pixel output/my-sprite.piskel --x 8 --y 8 --color "#ffffff" --jsonpiskel-cli export png output/my-sprite.piskel --json
piskel-cli export gif output/my-sprite.piskel --json
piskel-cli export frames output/my-sprite.piskel --json{
"steps": [
{ "command": "project.create", "args": { "width": 16, "height": 16, "name": "hero" } },
{ "command": "draw.rect", "args": { "project": "output/output.piskel", "x1": 3, "y1": 0, "x2": 12, "y2": 15, "color": "#4fc3f7", "filled": true } },
{ "command": "export.gif", "args": { "project": "output/output.piskel" } }
]
}piskel-cli run my-plan.json --json| Group | Commands |
|---|---|
| Project | project create, project info |
| Layer | layer list, layer add, layer remove, layer rename, layer set-opacity, layer move |
| Frame | frame list, frame add, frame remove, frame duplicate, frame move |
| Draw | draw pixel, draw pixels, draw line, draw rect, draw circle |
| Fill / Erase | fill area, erase pixel, clear frame |
| Read | read pixel, read frame, read project, read palette, read bounds |
| Export | export png, export gif, export spritesheet, export frames |
| Run | run <plan.json> — execute multi-step plan files |
| Serve | serve [<project.piskel>] — local HTTP + bundled Piskel web UI |
Full reference: docs/commands.md · 中文版 docs/commands.zh-CN.md
Every command supports --json for machine-readable output:
// Success
{ "ok": true, "data": { ... } }
// Failure
{ "ok": false, "error": { "code": "FRAME_INDEX_OUT_OF_RANGE", "message": "..." } }Consistent error codes across all commands make error handling simple in any language.
The run command executes a JSON plan file as an atomic sequence of steps — ideal for AI agents, build scripts, or complex multi-frame animations:
piskel-cli run examples/twinkle-star-plan.json --jsonSee examples/ for full working examples and skills/piskel-skill/reference/reference-plan-format.md for the complete plan format spec.
piskel-cli is implemented as a pure Node.js / TypeScript library with zero runtime browser dependencies. It operates directly on the .piskel JSON format:
src/probe/— headless read/write engine for.piskelfilessrc/cli/— command parser and JSON protocol layervendor/piskel-prod/— shipped copy of upstream Piskeldest/prod(used byserve; refreshed vianpm run sync-piskel-vendor)tests/— Vitest test suite covering.piskelI/O, CLI behavior, export correctness, and plan execution
npm install
npm run build # Compile TypeScript
npm test # Run full test suite (Vitest)
npm run test:watch # Watch modeFrom a local clone of piskelapp/piskel with npm install && npm run build already run:
npm run sync-piskel-vendor
# or: PISKEL_ROOT=/path/to/piskel npm run sync-piskel-vendorDetails: vendor/README.md.
Publishing: npm publish runs prepublishOnly, which ends with npm run assert-vendor. If vendor/piskel-prod/index.html is missing, publish fails so the registry package never ships a broken serve. Run sync-piskel-vendor before releasing.
Tests live in tests/ and cover .piskel read/write, CLI behavior, default output paths, and plan execution end-to-end.