CLI Reference¶
Global Options¶
These options apply to all subcommands.
-v, --verbose¶
Increase output verbosity. Repeatable up to four times:
| Flag | Level | Nix messages | junix messages | Unknown logs |
|---|---|---|---|---|
| (none) | 0 | errors, warnings | summaries | no |
-v |
1 | + notice, info | + progress, details | no |
-vv |
2 | same as 1 | same as 1 | yes |
-vvv |
3 | + talkative, chatty | same as 1 | yes |
-vvvv |
4 | + debug, vomit | same as 1 | yes |
Unknown logs are non-@nix lines, such as plain-text output from SSH remote builders.
Summaries and error: messages are always shown. Values above 4 count as 4.
The value can also be read from the JUNIX_VERBOSE env var (an integer 0–4). The
CLI value wins over the env var.
--color MODE¶
Control when ANSI colors are emitted in the terminal summary. This is a global switch on the parent command, so it must be placed before the subcommand:
Accepted values:
| Value | Behaviour |
|---|---|
auto |
Color when stderr is a TTY, otherwise no color. Default. |
yes |
Always emit color codes, even when stderr is piped. |
no |
Never emit color codes, even when stderr is a TTY. |
Resolution order (highest priority first):
--color MODEon the command line, when the user passes it explicitly. The flag always wins — even over the environment.JUNIX_COLORenv var, set to one ofauto/yes/no. Empty or unset is ignored.- Fallback
auto— color when stderr is a TTY, otherwise no color.
--help-all¶
Show the full help for all subcommands.
--version¶
Print the program version and exit.
With -v / --verbose, the version switch also prints diagnostic paths:
$ junix -v --version
junix 2.0.0
junix path: /home/yajo/.local/bin/junix
nix version: nix (Nix) 2.34.7
nix path: /nix/store/.../bin/nix
The junix path and nix path are resolved from the running interpreter / PATH,
falling back to the bare command name when the executable cannot be located. Symlinks
are resolved to their real targets. The verbose extras go to stderr; the first line
stays on stdout so plain junix --version remains machine-friendly.
translate¶
Pipe Nix build output into JUnit XML.
Reads @nix JSON protocol lines from stdin, parses them, and produces a JUnit XML
report on stdout (or to a file with -o).
While reading, junix translate immediately forwards lines to its own stderr:
- Non-
@nixlines are passed through unchanged from-vv. @nixlog messages are rendered in human-readable form (not raw JSON) according to the--verboselevel. Error messages are always forwarded.
This lets you watch a long build live while still capturing the JUnit report.
Options¶
| Option | Description |
|---|---|
-o, --output FILE |
Write XML to FILE instead of stdout |
-v, --verbose |
Increase Nix log verbosity (repeatable) |
Example¶
nix build --log-format internal-json -v --print-build-logs --no-link .#pkg1 2>&1 | junix translate -o result.xml
build¶
Run nix build and produce JUnit XML with a colorful terminal summary.
Runs nix build --log-format internal-json --keep-going for the given attribute paths,
parses the output, and produces a JUnit XML report.
A colorful summary is printed to stderr showing downloaded, cached, passed and failed
builds. The final line is PASSED (N/M) or FAILED (N/M builds).
The <testcase> name in the JUnit report is the exact command you would run to
reproduce the build: nix build <attr>.
Use -- to forward extra flags to nix build:
Options¶
| Option | Description |
|---|---|
ATTRS |
Flake attribute paths to build |
-o, --output FILE |
Write XML to FILE instead of stdout |
-s, --store URL |
Remote store URL (e.g. ssh-ng://builder) |
-v, --verbose |
Increase Nix log verbosity (repeatable) |
check¶
Discover, evaluate, and build all flake checks, producing a JUnit report and a colorful terminal summary.
Runs nix eval --json "path#checks" --apply to discover checks, then builds each one
with nix build --log-format internal-json --keep-going --no-link. Each check becomes a
test case in the JUnit report.
The build step targets the derivations the eval step already resolved
(/nix/store/….drv^out), not the flake attributes. Passing attributes would make
nix build evaluate the whole flake a second time — 41 s and ~2 GB on one real flake,
redoing work that was just done. Test case names still use the attribute, so the
reproducer in the report stays a command you can paste into a shell.
The report contains one <testsuite> per architecture and per phase:
nix-eval.{arch}— one testcase per check, with the derivation path in<system-out>on success, or<failure>if the check failed to evaluate.nix-build.{arch}— one testcase per check, with build logs in<system-out>on success,<failure>on build failure, or<skipped>when the build was cached.
The <testcase> name in the JUnit report is the exact command you would run to
reproduce the work: nix eval <path>#checks.<arch>.<name> for eval suites and
nix build <path>#checks.<arch>.<name> for build suites.
A colorful summary is printed to stderr with separate sections for eval and build
phases, per architecture. The final line is PASSED (...) or FAILED (...) with
separate counts of evals and builds — e.g. FAILED (0/4 evals, 1/2 builds).
Path must be a Nix-compatible flake reference
Junix does not rewrite the path you pass — what you give junix check is what
gets passed to nix eval and nix build. Like Nix itself, relative paths
must start with ./ or be an absolute path. For example:
Options¶
| Option | Description |
|---|---|
PATH |
Flake path (default: .) |
-o, --output FILE |
Write XML to FILE instead of stdout |
-e, --eval-arch ARCH |
Architecture to evaluate (default: all; repeatable) |
-b, --build-arch ARCH |
Architecture to build (default: local; repeatable) |
--eval-individually |
Evaluate each check in its own nix eval (slower, but better for low RAM scenarios) |
-j, --eval-jobs N |
Run N nix eval processes concurrently (default: 4) |
-v, --verbose |
Increase Nix log verbosity (repeatable) |
The -e and -b flags are independent. Passing -e aarch64-linux does not change the
default of -b (still local). Passing -b aarch64-linux does not change the default of
-e (still all).
--eval-individually is orthogonal to -e and -b. It only changes how each check
is evaluated (one nix eval per check instead of one bulk nix eval --apply per
flake), not which arches are evaluated. Use it when the default bulk evaluation OOMs
on large flakes — see Memory-constrained flakes
for details.
-j, --eval-jobs sets how many nix eval processes junix keeps in flight. It
defaults to 1, and raising it is a deliberate RAM-for-speed trade.
The win is large, because these processes are mostly idle — they wait on the store, on substituter round trips and on import-from-derivation builds. One observed eval spent 228 s of wall-clock on 5 s of CPU. On a 41-check flake:
-j |
wall-clock | peak RSS |
|---|---|---|
| 1 | 4m24s | 2.4 GB |
| 4 | 2m04s | 3.8 GB |
| 8 | 2m01s | 6.8 GB |
The reason it is not on by default is that Nix evaluation is the most memory-hungry
and least predictable step in the whole pipeline, and junix cannot guess your budget.
See NixOS/nix#8621: a modest NixOS config
evaluates in ~1 GB, one real nix flake show took >10 GB and froze a 16 GB laptop, and
16 GB CI runners hit the OOM killer on config evals. The heap uses a conservative Boehm
GC with no compaction, so it is never returned mid-process.
Failing that way is asymmetric: a slow junix check still writes a JUnit report, while
an OOM-killed one writes nothing and the CI job just dies with no results. So the
multiplier is yours to pick, on a flake and a runner you know. Measure before raising it
— and note the growth is sublinear, so -j 8 above bought 3 seconds for 3 GB.
-j inflates the reported eval time
<testsuite time> is the sum of its <testcase time> values (the JUnit
convention — see Timing). Each testcase still reports its own real
duration, but with -j 4 four of them overlap, so the suite total can read ~4×
the wall-clock you waited: 1.00s reported for 0.25s elapsed, in one measurement.
Parallel runners such as pytest-xdist behave the same way. Expect eval
durations in your CI dashboard to rise when you raise -j, even as the job
gets faster.
Example¶
# Run all checks
junix check -o check-report.xml
# Evaluate all arches, build only aarch64-linux
junix check -b aarch64-linux -o report.xml
# Evaluate only x86_64-linux, build only x86_64-linux
junix check -e x86_64-linux -b x86_64-linux -o report.xml
# Per-check eval (lower RAM peak, slower wall-clock)
junix check --eval-individually -o report.xml
# Pass extra flags to nix
junix check -- --no-link --rebuild
Extra flags after --¶
Flags after -- are forwarded to both phases, not just nix build. Evaluation
honours the same store settings as building, so a CI job can say where the whole run
should happen:
Without this, import-from-derivation builds triggered while evaluating would run on the local machine while everything else went to the remote builder.
The only flags held back from nix eval are the ones it rejects — --out-link/-o,
--no-link, --rebuild, --print-out-paths, --no-build-output, --dry-run — plus
--json/--pretty, since junix picks its own output format per call. Everything else
is passed through, because Nix accepts any nix.conf setting as a flag on any
subcommand. A flag Nix does not recognise will fail loudly rather than be dropped in
silence.
Environment variables¶
Every CLI flag accepts its value from a JUNIX_* env var. Precedence is CLI > env >
hard-coded default: passing the flag on the command line always overrides the env var,
and the env var overrides the built-in default.
This means CI runners can configure junix globally by exporting the variables, without having to wrap every invocation in a script that re-passes the same flags.
Naming convention¶
- Global flags (defined on the parent
junixcommand) useJUNIX_<FLAG>:JUNIX_VERBOSE,JUNIX_COLOR. - Subcommand flags use
JUNIX_<SUBCOMMAND>_<FLAG>, in upper snake case. Examples:JUNIX_CHECK_OUTPUT,JUNIX_BUILD_STORE,JUNIX_CHECK_BUILD_ARCH. - Hyphens become underscores, and case is ignored (upper snake case is the convention).
Mapping¶
| Flag | Environment variable |
|---|---|
-v, --verbose |
JUNIX_VERBOSE |
--color |
JUNIX_COLOR |
translate -o, --output |
JUNIX_TRANSLATE_OUTPUT |
build -o, --output |
JUNIX_BUILD_OUTPUT |
build -s, --store |
JUNIX_BUILD_STORE |
check -o, --output |
JUNIX_CHECK_OUTPUT |
check -e, --eval-arch |
JUNIX_CHECK_EVAL_ARCH |
check -b, --build-arch |
JUNIX_CHECK_BUILD_ARCH |
check --eval-individually |
JUNIX_CHECK_EVAL_INDIVIDUALLY |
check -j, --eval-jobs |
JUNIX_CHECK_EVAL_JOBS |
Value parsing¶
- String flags (
--output,--store,--color): the env value is used as-is. Empty values are treated as unset. - Counter flags (
--verbose): the env value must be a non-negative integer. Values above4count as4. Invalid values are ignored and the max value is used. - Numeric flags (
--eval-jobs): the env value must be a positive integer. Zero, negatives and non-numbers are ignored and the default is used. - Repeatable flags (
--eval-arch,--build-arch): the env value is split on commas and whitespace, soJUNIX_CHECK_BUILD_ARCH="aarch64-linux,x86_64-linux"is equivalent to passing-b aarch64-linux -b x86_64-linux. - Boolean flags (
--eval-individually): the env value follows the same rules as the rest of the CLI (1,true,yes,onare truthy;0,false,no,off, and empty are falsy).