CLI / Automation (overview)

Every operation in the app can be called headless — for scripts, pipelines and batch runs over a whole folder.

Summary

The app is also a command-line tool: the same processing you click in the interface runs headless for scripts, build pipelines and working through whole folders in batches. This page describes the global part — invocation, positional arguments, operations and the flags that several features share. The feature-specific flags and one example command each live in the "CLI / Automation" section of the respective feature page (see Per feature).

Invocation

Two equivalent ways:

# Python script (development / from the repo)
py -3.12 clean_sprite_chromakey.py [options] input output

# built application (release EXE)
clean_sprite_chromakey.exe [options] input output

In the examples on the feature pages, clean_sprite_chromakey.py stands in — replace it with the EXE on an installation. Help and version:

clean_sprite_chromakey.py --help        # full flag list (source of truth)
clean_sprite_chromakey.py --version

Positional arguments

Argument	Meaning
`input`	Input PNG (sprite sheet / asset).
`output`	Output PNG. For cutting operations (Slice / SliceX), the target/base path for the individual cells.
`--debug-output PATH`	Optional debug PNG, composited over `#00FF00` (alias `--preview-output`).

Both positional arguments refer to one file; the CLI has no folder mode. The CLI is the automation surface and is part of the Batch module — scripted batch (looping the CLI over a folder) requires the same entitlement as GUI batch; it is not a free way around the Batch module.

Choosing the operation (`--operation`)

Which processing runs is determined by --operation. The default is chromakey.

`--operation`	Feature	Flag group
`chromakey` (default)	Chroma-key profiles	`--profile` + the shared key flags
`undetail`	Pixel-art UnDetail	`--undetail-*`
`slice`	Asset Slice	`--slice-*`
`slice-grid`	Asset SliceX	`--slice-grid-xs` / `--slice-grid-ys`
`pixelize`	Pixelize	`--pixelize-*`

Choosing the profile (`--profile`, `chromakey` only)

With --operation chromakey, --profile picks the cleanup profile (default auto):

`--profile`	Feature
`auto`	Auto — measure the key per image, soft matte, passthrough with no key
`green`	Green Sprite
`green_hard`	Green Sprite (hard, content-safe)
`residue`	Residue Repair
`magenta_sprite`	Magenta Sprite / Outline
`magenta_fx`	Magenta FX / Water
`magenta_fx_plus`	Magenta FX / Water Plus
`custom`	Custom Color
`fx_glow`	FX / Glow (Soft Matte)

Shared flags

Several chroma-key profiles share these flags (details and sensible values on the respective feature page):

Flag	Effect	Applies to
`--key-color #RRGGBB` (alias `--chromakey-color`)	Key color as `#RRGGBB` or `R,G,B`. Default `#00FF00`.	Green / Green-Hard / Magenta-* / Custom
`--key-tolerance 0–160`	RGB distance tolerance (default 48).	Custom + Auto-Custom key
`--edge-cleanup {on,off}`	Edge cleanup; `off` removes only the background.	Green / Green-Hard / Magenta-* / Custom
`--spill-radius 1–4`	Width of the edge band — the spill radius (default 2).	Profiles with a fringe despill
`--spill-strength {conservative,normal,strong,maximum}`	Aggressiveness of the edge correction.	Magenta-* / Green repair
`--green-repair {off,soft,normal,strong}`	Black/Magic Outline Repair for contaminated green edges.	Green Sprite

Profile- or operation-specific flags (--residue-*, --fx-*, --undetail-*, --slice-*, --pixelize-*) are documented in the CLI section of the respective feature.

Utilities

Flag	Effect
`--check-update`	Checks the update feed and reports whether a newer version exists → Update check.
`--version`	Print the version number.
`--gui`	Opens the graphical interface instead of processing headless.
`--stamp-metadata`	Debug: writes the applied parameters as tEXt metadata into the output (mainly for the residue profile).

What's GUI-only

The following has no CLI counterpart — it lives only in the interface (--gui):

Interactive batch processing (file list, overwrite strategy, report, cancel) → Batch processing. The headless equivalent is the scripted CLI loop — both are part of the Batch module.
Eyedropper / picking the color from the image — on the CLI you give the key color directly with --key-color.
Live line dragging in Asset SliceX — on the CLI you give the cut positions numerically (--slice-grid-xs / --slice-grid-ys).
Preview / mask view, presets, "Open target folder" — pure interface convenience functions.

Per feature

Every feature page has its own "CLI / Automation" section with the relevant flags and an example command — this overview links there, the feature sections link back here:

Chroma-key: Green Sprite · Green Sprite (hard) · Residue Repair · Auto · Custom Color · Magenta Sprite · Magenta FX · Magenta FX Plus · FX / Glow
Transform: Pixel-art UnDetail · Asset Slice · Asset SliceX · Pixelize
Utility: Update check

clean_sprite_chromakey.py --help remains authoritative — in case of discrepancies, the app's output wins.