CLI reference
Options
| Option | Applies to | Meaning |
|---|---|---|
--manifest <path> | manifest commands | Manifest path; defaults to pixelkiln.manifest.json. |
--lock <path> | manifest commands | Lock path; defaults beside the manifest. |
--style a,b | most workflows | Restrict styles; repeatable. |
--only id1,id2 | most workflows | Restrict asset ids; repeatable. |
--budget <n|provider=n> | submit/gen/gallery | Refuse work above this cost. Repeat provider=n for every provider in a mixed run; do not mix keyed and unkeyed forms. For gallery, the session ceiling that enables generation from the page. |
--force | gen/fetch/derived commands/recipe install/quality snapshot | Regenerate current work, replace a changed or untracked fetch destination, rebuild current quality-profile output, take ownership of modified/unowned derived output, replace changed recipe files, or replace a changed quality baseline. A refinement rebuild resets approval. |
--dry-run | supported mutating commands | Inspect without spending or mutating provider state. |
--json | plan/doctor/audit/cache/status/gallery/salvage/refine/recipe/quality | Machine-readable stdout where supported. For gallery, prints the snapshot instead of serving it. |
--check | plan/audit/cache | Exit nonzero when selected state is unsafe. |
--yes, -y | confirmed operations | Skip an interactive confirmation. For refine approve, it records an already-completed human review; it does not replace one. |
--no-open | pick/salvage/gallery/edit | Do not automatically open the browser (open, xdg-open, or start, by platform), or the editor for edit. |
--edit | gallery | Let the page change asset prompts, sizes, category, and tags, and add assets. Rewrites the manifest only; never contacts a provider or spends. Also offers the in-browser editor. |
--no-editor | gallery | With --edit, do not offer, install, or serve the in-browser editor. |
--tag | fetch/adopt | Also push tags after the command's primary work. |
--refresh | fetch | Re-download downloaded outputs and replace files whose object changed upstream; never generates, never overwrites a local edit without --force. |
--claims <paths> | salvage | Other project lockfiles; repeatable and comma-separated. |
--workspace <path> | workspace/salvage/gallery | Workspace catalog path; defaults to pixelkiln.workspace.json for workspace. On salvage, derives the claim set instead of repeated --claims; on gallery, shows every registered project. |
--provider <id> | balance/adopt/salvage/purge/workspace add | Select the account provider for a mixed manifest, or set the workspace catalog's default provider hint. |
--account <label> | workspace add | Free-form account label, e.g. distinguishing sandboxes. |
--all | salvage dry run | List every unclaimed object rather than the first 30. |
--from <path> | init/refine/quality check | Existing source tree for init; source PNG or quality record for one-file refine mode; baseline for quality check. Omit it to use manifest style.quality. |
--exclude <names> | init | Directory/name fragments to exclude; repeatable. |
--generator <name> | init | Generator assigned to the scaffolded style. |
--name <name> | init | Project name for the scaffolded manifest. |
--write-prompts | adopt | Recover provider prompts into the manifest. |
--port <n> | pick/salvage/gallery | Local review or gallery server port; otherwise chooses a free port. |
--out <path> | pack/export/refine/recipe install/quality snapshot | Output base override, final native PNG for path-mode refine, exact recipe destination, or quality baseline path. Export requires one selected tileset. |
--inputs <path> | pack/quality snapshot | JSON input array; requires --out. Quality cases use { id, path, record?, tolerances? }. |
--columns <n> | pack/export | Grid columns, 1–1024; default is near-square. |
--format <name> | export, pack, mount | export: generic (default), tiled, or godot (TileSet). pack and mount: generic (default), aseprite (sheet JSON), or godot (SpriteFrames). |
--output-role <role> | pack | Include named structural roles; repeatable. |
--primary-only | pack | Include only unambiguous primary/single outputs. |
--max-distance <n> | audit | Absolute palette-distance ceiling. |
--min-transparency <0..1> | audit/refine | Minimum transparent canvas share. |
--max-colors <n> | audit | Maximum distinct opaque colors. |
--sigma <n> | audit | Relative outlier cutoff; defaults to 1.5. |
--prune | cache | Remove invalid and unreferenced cache data. |
--palette <hexes> | refine | Final #rrggbb colors; repeatable and comma-separated. Requires 2–256 unique colors. |
--fixer-python <path> | refine | One-run Python override containing Pixel Art Fixer. Manifest mode otherwise uses quality.fixerPython, then PIXELKILN_PIXEL_FIXER_PYTHON, then python3. |
--fixer-revision <sha> | refine | Revision recorded in the quality companion. Defaults to PixelKiln's tested pin. |
--min-grid-confidence <level> | refine | Minimum accepted detector confidence: high (default), medium, or low. |
--reviewer <name> | refine approve | Human reviewer stored in the quality companion. |
--note <text> | refine approve | Optional review note stored in the quality companion. |
--model-root <path> | recipe verify | ComfyUI models directory. Enables streamed hash checks for every external model declared by the recipe. |
--generation <n|hash> | restore | Bring a replaced generation back: 1 is the most recently replaced, or a prefix of one of its output hashes. One asset at a time. |