CLI reference

Commands
& flags.

The complete command-line surface implemented by the current Nox binary. Nox parses options manually, so the behavior below includes the defaults, precedence rules, and side effects that are easy to miss in a short usage line.

Global options

Options accepted by the parser.

Options may generally appear after any command. Unknown options, missing values, invalid job counts, and invalid paths fail with a configuration error. There are no command-specific flag aliases beyond the forms shown here.

--name NAMEstring

Set the generated project name for init. If omitted, init derives the name from the selected directory or detected package metadata.

--language LANGstring

Select the language for init instead of relying on detection. Supported language metadata includes Rust, C, C++, D, Haskell, Swift, F#, JavaScript, TypeScript, and Python.

--type TYPEstring

Select the generated project type for init, such as executable or library. When omitted, init infers the type from the project contents.

--template NAMEstring

Select an init template by name. The option is accepted by the CLI, but template generation is not currently implemented.

--formatternone

Ask init to create formatter configuration when the detected language and project rules provide one. Existing formatter files are preserved.

--no-noxfilenone

Prevent init from creating a noxfile. This only affects initialization and does not disable existing task files.

--no-nixnone

Prevent init from creating flake.nix or other Nix setup files. Existing Nix files are preserved.

-h--helpnone

Print help for the selected command and return success. It is recognized after the command; bare -h selects general help.

-v, -V--versionnone

Print nox VERSION and return success immediately. At the first argument position, it takes precedence over command parsing.

-C--build-dir PATHpath

Select the build directory. The default is build, then the path recorded in nox.config is used when no explicit directory was supplied. A positional directory for setup/build/compile overrides this option.

-j-jNpositive integer

Set the requested number of parallel build workers. -j requires a separate value; -jN accepts the value attached to the short option. The default is available_parallelism(), falling back to 1. Values are clamped to at least 1 by the executor.

--releasenone

Select the release configuration for setup, rebuild, install, and run configuration checks. The option is parsed for all commands, but build uses the configuration stored in nox.state.

--debugnone

Select the debug configuration. Debug is the default when no configuration option is supplied.

--reconfigurenone

For setup, remove the selected build directory before recreating its state. On other commands the value is parsed but has no command-specific effect.

--compile-flag FLAGstring

Append a compiler flag. Repeat the option to add multiple flags. Setup stores the flags in nox.state; build appends them for its invocation. Automatic setup inside install does not receive command-line compile flags.

--prefix PATHpath

Select the install prefix for install and uninstall. Relative paths are resolved from the current project root; the default is /usr/local on Unix or C:\Program Files\Nox on Windows.

Commands

Every supported command.

Aliases

Short names and equivalent dispatch.

b maps to build; r maps to run; configure maps to setup; compile shares build behavior; list shares targets behavior; stat shares status behavior; and bump shares bump-version behavior. test is a command shortcut for task test, not an alias in the command resolver.

Exit behavior

Output, errors, and status codes.

Normal output goes to stdout and errors go to stderr with anox: prefix. Configuration, parse, I/O, process, missing-tool, and build failures exit with code 1. A run child’s nonzero exit status is preserved; signal termination becomes 1. Task, compiler, linker, archiver, setup, and install failures are reported as Nox errors and exit with 1.

Output is colorized only when the relevant stream is a terminal. Set NO_COLOR to disable ANSI colors and terminal hyperlinks. Tool discovery uses the inherited PATH; Nox defines no other CLI environment variables.

Nox always treats the current working directory as the project root. It does not search parent directories for nox.build.

Related syntax

The files commands operate on.

nox.build defines project metadata, settings, targets, source paths or glob(...) patterns, dependencies, compiler flags, and install markers. noxfile defines optional named tasks. Setup writes nox.state andnox.config; VERSION supplies the project version used by version commands and task interpolation.

Read the nox.build reference →Read the noxfile reference →Return to Docs →