Inspect and Run Go's Built-in Tools with go tool

You will finish with a reliable way to discover the Go tools available to one installation, preview a command before it runs, and pass arguments to a selected tool without confusing them with go options. The examples were checked with the executable that reports go1.26.1 linux/amd64. The local Debian metadata reports golang-go 2:1.22~2build1, so check go version rather than assuming the package label describes the binary on your PATH.

Allow about ten minutes. You need a shell and a working Go installation. All steps below are ordinary, unprivileged commands. Do not use sudo: go tool selects or launches a tool, but it does not need administrator access for normal development work.

1. Confirm the Go executable

Start by checking which command will receive your request and which version it reports:

$ command -v go
/usr/local/bin/go
$ go version
go version go1.26.1 linux/amd64

Your path and version may differ. If command -v points somewhere unexpected, fix your shell environment before debugging a tool. Two Go installations can have different built-in tool directories and different module behaviour.

Checkpoint: the go version output is the version that matters for the next commands.

2. List the tools known to Go

Run go tool with no command. It prints the known built-in tools and exits without compiling your project:

$ go tool
asm
cgo
compile
cover
fix
link
preprofile
vet

The list is installation-specific. Do not treat it as a promise that every Go release exposes the same names. For help with one entry, ask that tool itself, for example:

$ go tool compile -h
usage: compile [options] file.go...
...

The compiler's full help is longer than the useful part shown here. The important distinction is that compile is the selected tool and -h is an argument passed to it.

3. Preview an invocation before running it

Use -n immediately after tool to print the command that would be executed:

$ go tool -n compile -h
/path/to/go/pkg/tool/linux_amd64/compile -h

The path varies with the Go installation. A preview is useful when a script, wrapper or multiple toolchains might be involved. It does not execute compile, even though the printed command includes -h.

Checkpoint: if the preview names the wrong Go tree, stop and correct PATH or select the intended toolchain before running the real command.

4. Pass the tool's arguments after its name

The command shape is go tool [-n] command args.... Put the tool name first, then its arguments. For a harmless check, ask the compiler for help without giving it a source file:

$ go tool compile -h
usage: compile [options] file.go...
...

Do not write go -h tool compile and expect the same result. The outer go command, tool subcommand and selected tool each have their own option parsing. Keep paths and values as separate, quoted shell arguments when they contain spaces or shell punctuation.

A real compilation is lower-level than go build. It normally needs compiler flags, import configuration and source files supplied by the Go build system. Use go build for ordinary package builds; reach for go tool compile when you specifically need compiler-level control or diagnostics.

5. Run a declared module tool when your project provides one

Recent Go versions can expose developer tools through tool directives in the current module's go.mod. Go 1.24 introduced the supported workflow for adding one with go get -tool. Inspect a project before changing it:

$ go env GOMOD
/home/user/project/go.mod
$ go mod edit -json | grep -A2 '"Tool"'
    "Tool": [
        "example.com/acme/cmd/checker"
    ]

Do not copy the example import path as though it were installed. Replace it with a tool declared by your own module. A declared tool can be invoked by its full package path, or by its final name when that name is unambiguous:

$ go tool example.com/acme/cmd/checker --help
$ go tool checker --help

These commands may resolve or build dependencies and can use the module cache. Review the module change before accepting it. To add a tool deliberately, use go get -tool PACKAGE_PATH; to remove that declaration, use go get -tool PACKAGE_PATH@none. Those commands change go.mod and possibly go.sum, so do not run them in a clean checkout without committing or reverting the intended change afterwards.

6. Diagnose a missing or surprising tool

A misspelt or unavailable name fails clearly:

$ go tool definitely-not-a-tool
go: no such tool "definitely-not-a-tool"

Check the no-argument list again, then check whether you are in the expected module directory. A declared tool is only available when the current directory is within the relevant module, or workspace mode selects that module. Use the full package path if the short name is ambiguous.

If a tool runs but behaves differently from a colleague's machine, compare go version, go env GOROOT GOPATH GOMOD and the relevant go.mod. The tool is tied to the Go command that launched it; changing PATH can silently change both the executable and its built-in tools.

Do not delete the module cache as a first fix. That is disruptive and can force downloads. First capture the exact command, version, module path and error, then test with go tool -n where it applies. If a module tool is untrusted, do not execute it merely because it is declared: review its source and dependency changes before running it.