CLI Reference

All commands are subcommands of go2nix. Set GO2NIX_DEBUG=1 for verbose output.

Commands you run

generate

Generate a lockfile from one or more Go module directories.

go2nix generate [flags] [dir...]

When no directory is given, defaults to .. Multiple directories produce a merged lockfile (monorepo support).

The generated lockfile is shared by both builder modes. Use buildGoApplication (default) or buildGoApplicationExperimental in Nix.

Examples:

go2nix generate .                       # write go2nix.toml in the current module
go2nix                                  # same — a completely bare invocation runs generate
go2nix generate -o lock.toml ./a ./b    # merged lockfile for two modules

generate reads each directory’s go.mod (its require and replace lines, so tidy it first) and downloads every module to hash it: it needs go on PATH and access to your GOPROXY. An existing output file is used as a cache, so a re-run only downloads what changed. -o is relative to the current directory, not to dir. Only the bare go2nix defaults to generate; go2nix ./dir or go2nix -o x.toml is an unknown command, and there is no top-level --help (each subcommand has -h).

See Lockfile Format for the output schema.

check

Validate a lockfile against go.mod.

go2nix check [flags] [dir]

Verifies that every go.mod requirement (filesystem replaces aside) has a path@version entry in the lockfile’s [mod]. It does not recompute hashes, look at [replace], or complain about entries that are no longer needed. It prints nothing and exits 0 on success; on failure it exits 1 with check failed and the missing modules. Notes: flags go before dir (go2nix check --lockfile x.toml dir), only one directory is taken, the default --lockfile is relative to the current directory, and a lockfile that does not exist reads as an empty one, so every module is reported missing.

Commands the builders run

compile-package, link-binary and test-packages are what the default mode’s derivations run; resolve is what the experimental mode’s wrapper runs (and it calls compile-package from the derivations it registers). You won’t normally run these; they are documented for debugging build failures. The manifests they read are JSON files the Nix side writes into the build directory.

compile-package

Compile a single Go package to an archive (.a file). Every per-package derivation runs it, in both modes: directly from the raw builder for pure-Go packages, through the compile-go-pkg.sh hook for cgo ones, and from the derivations go2nix resolve registers in experimental mode.

go2nix compile-package --manifest FILE --import-path PATH --src-dir DIR --output FILE [flags]

link-binary

Link Go application binaries. Reads a link manifest that declares all inputs (importcfg parts, local archives, ldflags, etc.), validates the lockfile, generates modinfo, compiles main packages, and invokes the linker. Used internally by the default mode’s build phase.

go2nix link-binary --manifest FILE --output DIR

test-packages

Compile and run the tests of the local packages that are part of the build. Used internally by the default mode’s check phase.

go2nix test-packages --manifest FILE

Discovers local packages with _test.go files, keeps those whose archive is in the manifest (the subPackages closure plus test-only helpers; the rest are skipped), compiles internal and external test archives, generates test mains, links test binaries, and runs them. See test-support.md for details on the test pipeline.

resolve

Build-time command for experimental mode (the nix/dynamic/ builder). Discovers the package graph, computes CA .drv paths in-process, registers them with the nix-daemon (falling back to nix derivation add if no daemon socket is reachable), and produces a .drv file as output. See Experimental Mode.

go2nix resolve [flags]

This command is not intended for direct use — it is invoked by the experimental-mode Nix builder inside a recursive-nix build.

Inspection tools

Not called by anything. They show what the builders see: which files go would pick in a directory, which packages a module has, what build information a binary would embed, what a generated test main looks like.

list-files

List Go source files for a package directory, respecting build tags and constraints.

go2nix list-files [-tags=...] [-go-version=...] <package-dir>

Outputs JSON with categorized file lists (Go files, C files, assembly, etc.).

-go-version sets the target Go toolchain version (e.g. 1.25) used to evaluate //go:build go1.N constraints; defaults to go env GOVERSION.

list-packages

List all local packages in a Go module with their import dependencies.

go2nix list-packages [-tags=...] [-go-version=...] <module-root>

Outputs JSON with each package’s import path and dependencies.

build-modinfo

Generate a modinfo linker directive for embedding debug/buildinfo metadata into the final binary. This is a standalone utility; the default mode’s link-binary command generates modinfo internally.

go2nix build-modinfo [flags] <module-root>

Outputs a modinfo directive for the linker’s importcfg (embedding debug/buildinfo metadata), and optionally a godebug line with the default GODEBUG value parsed from the module’s go.mod (used for -X=runtime.godebugDefault=...).

generate-test-main

Generate a _testmain.go file that registers test, benchmark, fuzz, and example functions. Standalone: the test runner generates its mains in-process with the same code, nothing calls this subcommand.

go2nix generate-test-main [flags]