Skip to content

NKit CLI

Jump to bottom
Nanook edited this page Sep 24, 2026 · 2 revisions

NKit is primarily a library with many features and options. The library uses a YAML config file to hold the various options. Applications using the library such as nkit can specify an alternative config if required.

This documentation reflects how the supplied command-line app (nkit / nkit.exe) functions. Please raise an issue if the app does not conform to this documentation and it will be bug fixed or the documentation updated.

Interactive Mode

Run nkit with no arguments (or drop a file onto the executable) to launch the interactive guided builder. It walks you through picking a task and options, then shows the equivalent command line so it doubles as a way to learn the CLI. Dropping a file pre-seeds it as the input and asks only for the remaining options.

# Launch interactive builder
nkit

# Drop a file — interactive launches with the file pre-seeded
nkit "Super Mario World (USA).iso"

Setup

NKit 3 releases are native AOT binaries — fully self-contained, single-file executables with no .NET runtime dependency. Download the appropriate archive for your platform and run directly.

Windows

  1. Download the Windows release archive and extract it
  2. On first run, Windows SmartScreen may show "Windows protected your PC" — click More info → Run anyway
  3. That's it. No runtime installation needed.

Linux

  1. Download the Linux release archive and extract it
  2. Make the binaries executable: 
    chmod +x nkit nkds nkit-ui nkds-ui
  3. Run: 
    ./nkit -task scan -in *.iso

Most modern distros (Debian 12+, Ubuntu 22.04+, Fedora 38+) have all required system libraries. If you encounter errors, check with ldd ./nkit.

Legacy builds (for older glibc systems) are also available.

macOS

  1. Download the macOS release archive and extract it
  2. Remove the quarantine attribute: 
    xattr -d com.apple.quarantine nkit nkds nkit-ui nkds-ui
  3. Make executable and run: 
    chmod +x nkit nkds nkit-ui nkds-ui
./nkit -task scan -in *.iso

Apple Silicon (M1/M2/M3/M4) uses the osx-arm64 build; Intel Macs use osx-x64.

Portable vs System Mode

On first run, NKit checks for a config file next to the executable:

  • Found → Portable mode (everything in the same directory)
  • Not found → System mode (config in OS-specific user location: %APPDATA%\nkit on Windows, ~/.config/nkit on Linux/macOS)

Input Parameters

This is a list of all input params supported by NKit. They can be set on the command line or read from a config file. By default nkit.yaml is loaded by the nkit app (matched by exe name). Parameter values in the config can be overridden by specifying them on the command line.

Required Parameters

Name Description
task Processing task to be performed. See Processing Tasks
in Input folder / file / archive / mask. See File Masks for detailed info. Config supports list format. Any bare CLI args (not -name value) are treated as input paths.

Supported Images: iso / rvz / wud / wux / tmd / wbfs+wbf1 / ciso / iso.dec / wia / gcz / nkit.iso / nkit.gcz / cue+bin / gdi / dec.iso / chd / cso / zso / dax / jso / xiso / app

Supported Archives: zip / zipx / rar / 7z / gz (including split and multi-volume)

Basic Parameters

Name Description Default
out Output path. Filenames calculated from processed files Source path
tmp Temp path. Written here first, moved to out on completion Source path
r Recursive in path search: y / n n
arc Search inside archives for images: y / n n
v Verify: y, n, datLookup y

Task-Specific Parameters

Name Description
convert Target format string (e.g. rvz:zstd:19:128k:16, wbfs, wux, ciso, app, deciso)
fixInfo Path to fix YAML (system-specific repair data)
fixFiles Path to directory of recovery/fix files
extract File mask or regex for Extract task filtering

General Parameters

Name Description Default
system Limit scanning to specified system All
keys Path/mask to key files, folder, or archive —
dat Path/mask to dat files (supports archive masks) —
outAsDatMatch Rename output to matched dat entry: y / n n
baseInPath Base path for unrecognised images —
scanOut Save path for NKit scan files —
scanIn Path to load scans (for verify/dedupe) —
consoleLevel Console output: none, info, detail, error, debug info
logOutLevel Log file detail level info
logOut Log file path —
results Enable per-image result logging: y / n n
resultsOut Results file path —
deleteProcessed Delete source on successful processing + verify: y / n n
skipIfCompleted Skip if output file already exists: y / n n

Keywords

Keywords can be used in path parameters. The default config uses them to dynamically specify file locations while processing.

Keyword Description
$appPath$ Path of the executable
$configPath$ Configuration directory
$userPath$ User data directory
$task$ Current task (lowercase)
$system$ Current system (lowercase) — not valid for in or tmp
$date$ Current date as yyyymmdd
$timestamp$ Current timestamp as yyyymmddhhmmss

YAML Configuration Files

The config file specifies parameters and defaults for all NKit features. It serves as a reference allowing users to easily browse and edit settings.

Configuration parameters are split into types:

  • Root level — Applied before processing begins
  • System level — Per-system overrides (e.g. different dat paths per system)

System level params override Root level parameters of the same name when present. The params task, system, in, r, arc, logOut, logOutLevel, consoleLevel are root level only.

The default nkit.yaml can be overridden with the -cfg parameter:

nkit -cfg other.yaml -task scan -in *.*

Disable config entirely:

nkit -cfg n -task convert -in *.iso -convert rvz

Per-System Values

Params can be specified per system by prefixing:

nkit *.iso -task convert -wii:convert rvz:zstd:19:128k:16 -gamecube:convert rvz:zstd:19:64k:8
nkit *.iso -wii:dat Wii*.dat -gamecube:dat GC*.dat

Clone Workflow

Clone the nkit executable and create a matching YAML for task-specific tools:

rvzconvert.exe + rvzconvert.yaml → rvzconvert *.iso (convert to RVZ)
wuxconvert.exe + wuxconvert.yaml → wuxconvert *.wud (convert to WUX)

Dragging files onto the cloned app processes them with the matching config. The bundled rvzconvert and wuxconvert demonstrate this pattern.

Command-Line Overrides

Command-line parameters supplement the config file. Parameter names are prefixed with - in the format -name value.

Any parameters not in -name value format are treated as input (in) paths/masks. This allows dragging files onto the app to process them using the default config.

If you need to specify an input starting with -, use the -in parameter explicitly or prefix with -- (everything after -- is treated as input paths only).

Examples

# Load default config, scan for iso files
nkit -task scan -in *.iso -r y

# Multiple inputs
nkit *.iso *.rvz "../other path/*.wbfs"

# Override one system's convert format
nkit *.iso -task convert -wii:convert wbfs

# Use alternate config
nkit -cfg rvzconvert.yaml *.iso

# Clone app (loads rvzconvert.yaml automatically)
rvzconvert *.iso

# No config, explicit params
nkit -cfg n *.iso -task convert -convert rvz:zstd:19:128k:16

# Everything after -- is treated as input
nkit -task scan -- -weirdly-named-file.iso another.rvz

Exit Codes

Code Meaning
0 Completed successfully
1 Completed with one or more failed images
2 Required parameters not specified
3 Config file error
4 Log file write error
5 Results file write error
6 Unknown error
7 Cancelled (Ctrl+C / SIGINT)

Clone this wiki locally