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 — generate is the default when no subcommand is given
go2nix generate -o lock.toml ./a ./b    # merged lockfile for two modules

See Lockfile Format for the output schema.

check

Validate a lockfile against go.mod.

go2nix check [flags] [dir]

Verifies that all go.mod requirements are present in the lockfile with correct versions.

Internal commands (invoked by the Nix builders)

You won’t run these directly; they are documented for debugging build failures.

compile-package

Compile a single Go package to an archive (.a file). Used internally by the default mode’s setup hooks.

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

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.

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.

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. Used internally by the test runner.

go2nix generate-test-main [flags]

test-packages

Compile and run tests for all testable local packages in a module. Used internally by the default mode’s check phase.

go2nix test-packages --manifest FILE

Discovers local packages with _test.go files, 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.

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