Command Line

NextDither ships two programs. NextDither.exe is the window you open to adjust an image and see what the conversion did to it. NextDither-cli.exe does the same conversion without a window, so a build script can run it.

They share everything that matters: the same conversion core, the same presets, the same output files.

When to use which

Use the GUI to work out what settings a project needs. Framing, tone and dither are judged by eye against a live preview, and there is no way to judge them from a command line.

Use the CLI once those settings are saved as a preset and the job is to apply them again - converting a folder of artwork as part of a build, re-exporting after the art changes, or checking that a set of images still converts cleanly.

Your first conversion

Open a terminal in the folder you unzipped NextDither into.

NextDither-cli.exe convert art\ --out gfx\ --overwrite force

That converts every image in art\ using the built-in NextDAAD Layer 2 preset and writes the results into gfx\.

You can also name files directly, or use a pattern:

NextDither-cli.exe convert art\cellar.png --out gfx\
NextDither-cli.exe convert art\room*.png --out gfx\

A folder is scanned one level deep, so a wip\ subfolder of unfinished work is left alone.

Using your own preset

Save a preset in the GUI, then use it by name:

NextDither-cli.exe convert art\ --out gfx\ --preset "My Game"

If the name is not found, ask what is available:

NextDither-cli.exe presets list

That prints the presets it can see and the folder it read them from, which is usually enough to explain a name that did not work.

A preset kept beside your source art works too - pass its path instead of a name:

NextDither-cli.exe convert art\ --out gfx\ --preset art\my-game.toml

Changing one setting for one run

A preset is the baseline. Anything you need to vary per run has a flag:

NextDither-cli.exe convert art\ --out gfx\ --preset "My Game" --colours 200

See the command reference for the full list.

Settings that need a preview to judge - brightness, contrast, gamma, saturation, the spatial filter, the colour metric - have no flags. Set those in the GUI and save them into a preset.

Seeing what would happen first

--dry-run reports the files a run would write, the ones that already exist and any name collisions, without converting or writing anything:

NextDither-cli.exe convert art\ --out gfx\ --dry-run

Existing files

By default NextDither will not overwrite anything and will not guess. If outputs already exist, the run stops and tells you so, and nothing is touched. Pass a decision to continue:

NextDither-cli.exe convert art\ --out gfx\ --overwrite force
NextDither-cli.exe convert art\ --out gfx\ --overwrite skip

force replaces the existing files. skip leaves them alone and converts nothing.

In a build script

The exit code says what happened, so a script can react to it. See exit codes.