CLI Commands
Command reference
NextDither-cli.exe convert [OPTIONS] <INPUT>...
NextDither-cli.exe presets list
NextDither-cli.exe --help
NextDither-cli.exe --version
convert
Converts images and writes the formats the preset asks for.
Inputs
One or more files, folders or patterns.
- A folder is scanned one level deep, and only files NextDither can open are used. Subfolders are ignored.
- A file named directly is always used, whatever its extension.
- A pattern containing
*or?is matched against the folder it names -art\room*.png. Only the file name part may contain those characters. Windows does not expand patterns before the program sees them, so NextDither does it.
Files are converted in filename order, so {n:3} numbering is the same every run.
Supported input types: png, jpg, jpeg, bmp, tif, tiff, webp.
Required
| Flag | Meaning |
|---|---|
--out <DIR> |
Where to write the converted files. Created if it does not exist. |
There is no default. Writing into the current folder or beside the source art would both scatter output somewhere you did not ask for.
Choosing a preset
| Flag | Meaning |
|---|---|
--preset <NAME|PATH> |
A saved preset's name, or a path to a .toml preset file. |
Without it, the built-in NextDAAD Layer 2 preset is used. It is also accepted by name, as "NextDAAD Layer 2" or nextdaad-layer2. If you have saved a preset of your own literally named nextdaad-layer2, that saved preset is used instead - the slug only falls back to the built-in when nothing is saved under it.
An argument containing \ or /, or ending in .toml, is treated as a file path. Anything else is treated as a name.
Overrides
Each of these replaces one setting from the preset for this run only.
| Flag | Values |
|---|---|
--width <PIXELS> |
Output width. |
--height <PIXELS> |
Output height. |
--fit <MODE> |
stretch, letterbox, crop-fill |
--anchor <WHERE> |
top-left, top-centre, top-right, centre-left, centre, centre-right, bottom-left, bottom-centre, bottom-right |
--palette <MODE> |
wu, kmeans, rgb332 |
--colours <N> |
How many palette colours to generate. |
--dither <KIND> |
none, floyd-steinberg, jarvis, stucki, burkes, sierra3, two-row-sierra, sierra-lite, atkinson, stevenson-arce, bayer2, bayer4, bayer8, bayer16, blue-noise |
--dither-strength <AMOUNT> |
0.0 to 1.0. |
--format <LIST> |
Comma separated: bitmap, zx0, nxp, png |
--naming <PATTERN> |
Output naming, for example {stem}.{ext} or {n:3}.{ext}. See the preset file. |
--overwrite <WHAT> |
skip or force |
Brightness, contrast, gamma, saturation, the spatial filter, the colour metric, serpentine scanning, forbidden colours, the slot policy and the transparency slot have no flags. They are judged against a preview, so they belong in a preset.
An override that produces an impossible setting - a frame size the NextDAAD loader would refuse, for instance - fails before any image is read.
Other options
| Flag | Meaning |
|---|---|
--dry-run |
Report what would be written. Converts nothing, writes nothing, and does not create the output folder. |
--quiet |
Print only failures and the final summary. |
presets list
Prints the presets NextDither can see and the folder it read them from.
The built-in preset is always listed, even though it has no file.
Where presets are stored
The CLI and the GUI read the same folder, so a preset saved in one is available to the other. presets list prints the exact path.
NextDither prefers a presets folder beside the executable when it can write there, which keeps an unzipped copy self-contained. Otherwise it uses your user configuration folder.
Output
Results are printed in queue order. Progress is printed to the error stream, so redirecting normal output to a file keeps the log clean:
NextDither-cli.exe convert art\ --out gfx\ --overwrite force > build.log