Configure Netsuke

Updated Aug 05, 2026

Configuration precedence, from lowest to highest, is:

  1. Built-in defaults.
  2. System configuration.
  3. User configuration.
  4. Project .netsuke.toml.
  5. NETSUKE_ environment variables.
  6. Explicit command-line options.

System and user configuration are discovered from platform conventions rather than two separately named Netsuke layers. On Unix this means the XDG base directories and the home directory; on Windows it means the application-data directories, such as %APPDATA%\netsuke\config.toml. Their relative order follows those platform conventions.

An explicit selector bypasses automatic discovery. Selectors are checked in this order:

  1. --config <PATH>
  2. NETSUKE_CONFIG=<PATH>

An explicit file that is missing or invalid causes an error; Netsuke does not fall back to discovery.

Diagnose configuration selection

Pass --verbose to see how Netsuke selected its configuration. Structured events report whether --config, NETSUKE_CONFIG, or automatic discovery won, whether a path was present, and which environment lookups were attempted. Events then identify whether Netsuke uses an explicit file or discovered layers.

If an explicit file cannot be loaded, the warning records failure_kind as Missing or LoadError. Path fields are bounded to path_hash and path_file_name; full paths and formatted parser errors are not tracing fields. The file name is visible, and the unkeyed hash is only a correlation identifier: it does not confidentially conceal a guessable path.

Configuration tracing is disabled in JSON mode, including when json = true comes from a configuration file. This keeps stderr empty for successful JSON commands and reserves it for the single diagnostic document on failure.

The annotated sample configuration lists every key. A small project configuration looks like this:

jobs = 4
verbose = true
locale = "en-US"
json = false
no_input = true
color = "never"
emoji = "never"
progress = "never"
accessibility = "on"
default_targets = ["hello.txt"]

Common environment equivalents include:

  • NETSUKE_JOBS=4
  • NETSUKE_VERBOSE=true
  • NETSUKE_JSON=false
  • NETSUKE_NO_INPUT=true
  • NETSUKE_COLOR=never
  • NETSUKE_EMOJI=never
  • NETSUKE_PROGRESS=never
  • NETSUKE_ACCESSIBILITY=on
  • NETSUKE_LOCALE=en-US
  • NETSUKE_DEFAULT_TARGETS__0=hello.txt
  • NETSUKE_NINJA=/opt/ninja/bin/ninja

NETSUKE_LOCALE selects the interface language; see Choose a language with --locale for how it combines with the flag and the system default.

NETSUKE_NINJA overrides the Ninja executable used by build and clean. Leave it unset to use ninja from PATH, or set another executable name or an absolute path. Empty and non-UTF-8 values fall back to the default.

The CLI and configuration use the same policy values. auto follows terminal and environment detection. always or never makes colour, emoji, or progress behaviour explicit. Accessibility uses on and off for its explicit values.

Netsuke has no interactive mode. It never prompts, and no_input = false is rejected. Pass root --no-input in automation to state that requirement explicitly and make the invocation self-documenting.