Reference

CLI reference

Every command and flag, including gallery, edit, history, tools, the PixelLab unzoom, pixelate, vfx, font, estimate-skeleton, and skeleton-preview utilities, automation, and exit behavior.

pixelkiln <command> [options]

Unknown commands, positional arguments, and flags are errors. The only positional words accepted are a command's own subcommands (refine approve, workspace add <manifest>, and the like), estimate-skeleton's one image path, and skeleton-preview's keypoints file or asset id. Repeated --style, --only, --claims, and --output-role values accumulate; comma-separated values work too. This strict parsing prevents a misspelled filter from widening a paid run.

The manifest's top-level provider is the default; each style may select a different provider. plan, doctor, and pipeline commands route the resolved work accordingly. The experimental retrodiffusion adapter supports still-image map/pixflux, tiles sheets, and animation GIF/spritesheet work. The experimental comfyui adapter runs committed API-format map and ordered still-frame workflows on a self-hosted server. The experimental scenario adapter runs hosted still models, with reference-image edits, Compute Unit preflight, and durable asset recovery.

Which command:

I want to	Run
see what a run would do and cost, spending nothing	`pixelkiln plan`
generate everything the manifest still needs	`pixelkiln gen --budget 40`
hold every generated file to the style's palette	set `"enforcePalette": true` on the style, then `pixelkiln fetch`
draw a character in 8 directions, then its poses and loops	a `character` style with `state` and `animation` assets; one `pixelkiln gen` runs the waves
rotate your own sprite into 8 directions	`"reference": "refs/bot-south.png"` on the base; `mode: pro-flash` does it for 1 generation at 64px
get the east-facing loop without paying for it	`"bot.walk.east": { "mirror": "bot.walk.west" }`
declare one loop for several directions, mirroring the rest	`"animation": { "of": "bot", "directions": ["south", "west", "north"] }`; `--only bot.walk` selects the whole family
make a bust portrait, or re-clothe a loop from an outfit image	`"portrait": { "of": "mira", "size": 64 }`, `"outfit": { "of": "mira.walk", "reference": "refs/armor.png" }`
generate one asset, or one style	`pixelkiln gen --only anvil --budget 2`, `pixelkiln gen --style neon --budget 20`
finish a run that was interrupted	`pixelkiln plan`, then the `next:` command it prints (`poll`, `pick`, or `fetch`)
choose among candidates the provider returned	`pixelkiln pick`
get back a generated file I deleted or lost	`pixelkiln restore`
bring back the generation a regeneration replaced	`pixelkiln history`, then `pixelkiln restore --only anvil --generation 1`
look at everything the project has made	`pixelkiln gallery`
change prompts and sizes, or regenerate, from the browser	`pixelkiln gallery --edit --budget 10`
touch a sprite up by hand and keep the edit	`pixelkiln edit --only anvil`
stop tracking a hand edit	`pixelkiln edit detach --only anvil`
build a sprite sheet	`pixelkiln pack --style base`
place sprites on a sheet at declared cells	`pixelkiln mount --style base`
export a tileset for Tiled or Godot	`pixelkiln export --style ground --format tiled`
get a sheet Phaser, Unity, or Godot loads as animations	`pixelkiln pack --style hero --format aseprite` or `--format godot`
check the art against the style's palette and grid	`pixelkiln audit --style base`
produce the palette-clean, grid-true final art	`pixelkiln refine` then `pixelkiln refine approve --from <record> --reviewer "Name"`
claim art already on my provider account	`pixelkiln adopt`
find paid work on the account that no lockfile claims	`pixelkiln salvage`
accept reworded prompts without regenerating	`pixelkiln accept`
drop lock entries the manifest no longer declares	`pixelkiln prune`
check the project before committing or in CI	`pixelkiln doctor`, `pixelkiln plan --check`
see the account balance	`pixelkiln balance`
shrink upscaled outside art to its native grid before using it as a reference	`pixelkiln unzoom --from refs/knight-512.png --out refs/knight.png`
turn a photo, painting, or render into pixel art	`pixelkiln pixelate --from renders/lodge.png --out art/lodge.png`
make a normal map so an engine can light a sprite or a loop strip	`pixelkiln normal-map --from art/hero-walk.png --frames 6`
make a pixel-art effect (spell, hit, explosion, aura), free	`pixelkiln vfx --preset explosion --out fx/explosion`
generate a pixel font (`.ttf` plus glyph atlas)	`pixelkiln font --description "warm orange arcade font" --out fonts/arcade`
start an `animate-skeleton` keypoints file from an image	`pixelkiln estimate-skeleton poses/hero.png --out poses/hero-swing.json`
see a keypoints file's poses over the source before paying	`pixelkiln skeleton-preview hero-swing`
work across several projects	`pixelkiln workspace add ../other/pixelkiln.manifest.json`, then `--workspace` on `gallery` and `salvage`

Every command takes --manifest <file> when the manifest is not in the working directory. Commands that spend take --budget; commands that replace a file you changed take --force.

Everyday pipeline

init

Prompts are deliberately empty because plausible text is not provenance.

plan

Diff the resolved manifest against the lockfile and disk without calling a provider.

doctor

Validate the manifest, references, lockfile recovery sources, raw and quality output paths, stale jobs, current plan, credential configuration, and provider connectivity.

gen

Run submit → poll → pick → fetch.

submit

Queue selected missing/stale generation work without polling it.

poll

Advance submitted jobs to completed, failed, or selection-ready states.

pick

Open the local candidate-review UI for jobs with alternatives.

fetch

Download completed or selected outputs, validate complete PNG or GIF structure, write the manifest-authoritative destinations, populate the content cache, and update output hash…

restore

Repair missing generated files without buying new generations.

history

List, per asset, the current generation and the ones it replaced, newest first, with each one's hash, download time, object id, and whether the prompt differed.

Reconciliation and lifecycle

adopt

Match local files to existing provider objects by SHA-256.

accept

Re-baseline intact existing art after prompt/style prose changes.

salvage

Review remote objects that no supplied lockfile claims.

purge

Delete provider objects and characters previously tagged pixelkiln:discard.

prune

Remove lock entries that no style/asset pair in the manifest resolves to.

tag

Push current manifest tags to tracked provider objects.

balance

Show one provider's remaining balance and cost unit.

status

Summarize lock entries by state and successful submission spend by cost unit.

edit

Hand-edit one asset in the editor you already use, without touching the generated file.

tools

Prepare the in-browser editor before opening a gallery, or check what is on disk.

gallery

Open a local, read-only gallery of everything the project has generated.

workspace

Register sibling projects in a schema-versioned catalog file, outside any one manifest, so a shared provider account's complete claim set no longer depends on remembering every…

recipe

Manage versioned provider setup packs without contacting a provider.

Local quality and derived output

audit

Measure palette distance, transparent canvas share, and opaque color count for every selected output.

refine

Build or verify the quality profile declared by selected manifest styles.

quality

Snapshot measurable PNG traits, then fail CI when committed assets drift beyond their reviewed envelope.

cache

Inspect the local content cache and account object-hash cache.

pack

Build a deterministic RGBA sprite sheet, JSON atlas, and .pixelkiln.json provenance companion.

mount

Write sprites into manifest-declared cells, optionally over an existing base sheet.

export

Build a structural tile atlas plus generic JSON, Tiled TSJ, or Godot TRES metadata and a provenance companion.

PixelLab utilities

Three commands call PixelLab on loose files rather than manifest assets. None reads the manifest or touches the lockfile; all three load PIXELLAB_API_KEY from the environment or a .env.local/.env beside --manifest or in the working directory, the same as every other command. A fourth, skeleton-preview, is their local companion and calls nothing.