Use the command-line interface

The top-level command shape is:

netsuke [OPTIONS] [COMMAND]
netsuke [OPTIONS] build [TARGETS]...

Global options must appear before the subcommand. For example, netsuke --color always build is valid; netsuke build --color always is not.

The commands are:

• build [TARGETS]...: generate Ninja and build the named targets. With no targets, use configured defaults and then manifest defaults.
• clean: generate a temporary Ninja file and run ninja -t clean.
• graph: render the build graph as DOT or self-contained HTML without invoking Ninja.
• generate: write Ninja without invoking it. Outside JSON mode, the generated Ninja manifest is the only content written to stdout; use --output <FILE> to write it to a file instead. In JSON mode (--json) the manifest is carried in the result document's result.content field instead.
• help [TOPIC]: print the top-level help, or the help for a named topic. With no topic, it matches --help. help targets prints the target and action catalogue for the selected manifest (see Generate and inspect artefacts).

Running netsuke without a subcommand is the same as netsuke build with no explicit targets. A bare target such as netsuke hello is not accepted; use netsuke build hello.

Important global options include:

• -f, --file <FILE>
• -C, --directory <DIR>
• --config <FILE>
• -j, --jobs <N> (accepts 1 to 64)
• -v, --verbose
• --locale <LOCALE>
• --no-input
• --json
• --color <auto|always|never>
• --emoji <auto|always|never>
• --progress <auto|always|never>
• --accessibility <auto|on|off>
• --default-target <TARGET>

Run netsuke --help or netsuke <command> --help for the complete current surface.

Netsuke's help text, validation errors, progress labels, and runtime diagnostics are translated. The locale is chosen by the first source that yields a valid BCP 47 tag, and which sources are available depends on when the message is rendered.

Help, usage, and command-line validation errors are produced before any configuration file is read, so they use the --locale flag, then NETSUKE_LOCALE, then the system default, then en-US. Diagnostics, progress, and status output are rendered after the configuration merge, so they consult the configuration file's locale setting as well, between NETSUKE_LOCALE and the system default.

System values are normalized first, so en_GB.UTF-8 is understood as en-GB.

Table 1: Locales Netsuke ships

en-US is the source locale. Any message a translation has not yet covered falls back to the English text rather than disappearing.

A requested tag resolves by these rules, in order:

1. The exact tag, if a catalogue carries it.
2. A script or region rule for that language. Bare es and es-ES use es-ES, and every other Spanish region uses es-419; bare pt and every Portuguese region except Brazil use pt-PT; Chinese resolves by script, with zh-CN, zh-SG, and zh-MY taking Simplified and zh-TW, zh-HK, and zh-MO taking Traditional; English outside the United States uses en-GB; and no resolves to nb.
3. The only catalogue for that language, so fr-CA uses fr and de-AT uses de.
4. en-US, for anything still unmatched.

Regional and script variants that differ in substance are never merged: asking for pt-BR never yields European Portuguese, and asking for zh-TW never yields Simplified Chinese.

Manual pages and PowerShell help shipped in releases are generated in en-US only. Translated copy reaches users through the running binary, which embeds every catalogue. The generated help describes the complete public CLI, including -C/--directory, --config, and the documented command tree.

--directory changes manifest lookup, project configuration discovery and relative output paths:

netsuke --directory /path/to/project build

--directory affects manifest lookup, automatic project-configuration discovery, and relative output paths. It does not rebase an explicit --config path or NETSUKE_CONFIG value: a relative selector resolves from the process working directory, while an absolute selector remains unchanged. Pass an absolute path when the selector must not depend on the invoking directory.

These commands cover the non-default utility workflows:

netsuke clean
netsuke graph --output build.dot
netsuke graph --html --output graph.html
netsuke generate
netsuke generate --output build.ninja

graph is rendered in-process and does not require Ninja. DOT goes to stdout unless --output is supplied. HTML output contains a server-rendered SVG, a textual outline and a <noscript> DOT representation.

generate writes Ninja without running it. With no --output, stdout contains only the generated Ninja manifest. With --output <FILE>, Netsuke writes the manifest to that file and leaves stdout empty. For a serial dependency list, both forms also materialize the referenced sidecars under .netsuke/dyndep in the effective Ninja working directory, so the emitted manifest is executable at that point. Retention is bounded: a later Netsuke command may remove sidecars referenced by an older arbitrary output file. Regenerate the file when that happens.

clean removes file outputs tracked by Ninja. Phony targets and actions do not represent files and are not removed.

help targets prints the target and action catalogue for the selected manifest — actions first, then targets — with a localized default marker such as [★ default] (or [* default] in accessible output) on manifest defaults and an empty description column for entries without a description:

netsuke help targets

The command loads, expands, renders, and validates the manifest through the same structural stages as a build, but performs no recipes and creates no build outputs. Rendering uses a restricted, side-effect-free Jinja surface. Queries allow only the lexical path filters basename, dirname, with_suffix, and relative_to, the collection filters uniq, flatten, and group_by, and the clock-independent timedelta function. Query rendering skips command and script recipe bodies, so build-only helpers in those recipes are not evaluated and do not make discovery fail. Metadata such as vars, names, dependencies, and descriptions is still rendered; structural rule selectors are rendered as needed for graph validation.

Queries reject direct use of env() and glob(), file tests, filesystem metadata filters such as size and linecount, hash, digest, contents, realpath, and expanduser, executable discovery through which and command_available, network and command helpers (fetch, shell, and grep), and the clock-dependent now() function. A helper from this disabled set in a when expression cannot be evaluated safely during discovery, so its entry is retained and marked conditional, but that unresolved alternative is excluded from graph validation. An ordinary false when expression still filters its entry out. Normal build manifest rendering retains the full standard library and its existing when semantics; these restrictions apply only to query rendering.

In human-readable output, a conditional entry carries [◇ conditional] when emoji output is allowed, or [? conditional] in the ASCII theme. JSON output always includes a boolean conditional field: true means that discovery could not resolve the entry's when expression, while false means no such uncertainty was recorded. Integrations should therefore preserve conditional entries rather than treating them as confirmed selections. The command honours the usual manifest-selection options (--file, -C/--directory) and the normal colour, accessibility, locale, and JSON-output conventions; with --json the catalogue is emitted as a versioned JSON document whose result.command is help-targets.

The standard-library reference describes the full helper set available while rendering a normal build manifest. The query allowlist above is the deliberate exception for netsuke help targets.

Recipe-body skipping and conditional catalogue entries are beta3 behaviour. Published beta2 help targets does not provide those semantics.