Command Structure and Help

Every interaction with Go's toolchain begins with the same two characters: go. The command's syntax is simple on the surface — a single binary that dispatches to subcommands — but the way you ask it for help determines how fast you find answers. This section covers the structure of go invocations and the help system that makes the entire toolchain self-documenting.

The go Command Syntax

A go invocation has a fixed shape:

go <command> [arguments]

The first word after go is always a subcommand that tells the tool what to do. Everything that follows — flags, package names, file paths — supplies how and where to do it.

go build -o myapp ./cmd/server

Here build is the subcommand, -o myapp is a flag with a value, and ./cmd/server identifies the package to build.

The subcommand is not optional. Running go with no arguments prints a short help overview but does not perform any work. Every meaningful operation — compiling, testing, formatting, managing dependencies — lives behind one of the dozen or so subcommands the binary carries.

Getting Help from the go Command

Go ships its own documentation inside the tool. No internet connection is required, and you never need to leave the terminal. The help system is the fastest way to recall a flag you forgot or to discover what a subcommand does.

The top-level help overview

Running go help (with no subcommand) prints every available command and a list of additional help topics:

go help

The output looks roughly like this:

Go is a tool for managing Go source code.
Usage:
        go <command> [arguments]
The commands are:
        bug         start a bug report
        build       compile packages and dependencies
        clean       remove object files and cached files
        doc         show documentation for package or symbol
        env         print Go environment information
        fix         apply fixes suggested by static checkers
        fmt         gofmt (reformat) package sources
        generate    generate Go files by processing source
        get         add dependencies to current module and install them
        install     compile and install packages and dependencies
        list        list packages or modules
        mod         module maintenance
        work        workspace maintenance
        run         compile and run Go program
        telemetry   manage telemetry data and settings
        test        test packages
        tool        run specified go tool
        version     print Go version
        vet         report likely mistakes in packages
Use "go help <command>" for more information about a command.
Additional help topics:
        buildconstraint   build constraints
        buildjson         build -json encoding
        buildmode         build modes
        c                 calling between Go and C
        cache             build and test caching
        environment       environment variables
        filetype          file types
        goauth            GOAUTH environment variable
        go.mod            the go.mod file
        gopath             GOPATH environment variable
        goproxy           module proxy protocol
        importpath        import path syntax
        modules           modules, module versions, and more
        module-auth       module authentication using go.sum
        packages          package lists and patterns
        private           configuration for downloading non-public code
        testflag          testing flags
        testfunc          testing functions
        vcs               controlling version control with GOVCS
Use "go help <topic>" for more information about that topic.

The top of the output gives you a choice: pick a command for operational tasks, or pick a topic for conceptual documentation. Both paths lead to further detailed help.

Help for a specific subcommand

To learn everything about one subcommand, add its name after help:

go help build

This prints the subcommand's usage line, a description of what it does, and every flag it accepts. For example, go help build explains the -o flag, the handling of _test.go files, and how the output binary is named when you pass a list of .go source files.

The go command treats subcommand help as a primary navigation path. If you ever forget a flag that belongs to go test, you do not need to search the web — you run go help test and scroll to the flags section.

Help for a conceptual topic

The "Additional help topics" section covers subjects that are not subcommands but govern behavior across multiple commands. Run the same syntax:

go help gopath
go help modules
go help packages

These pages define conventions and environment variables. They are especially useful when you encounter errors about module requirements or package resolution, because the explanation of what the tool expects is already on your machine.

The -h shortcut on subcommands

Most subcommands accept a -h or --help flag directly, without the help subcommand:

go build -h
go test -h

This produces the same detailed output as go help build or go help test. The shortcut exists because many developers are accustomed to -h from other tools, and the go command accommodates that muscle memory.

However, the go binary itself — before a subcommand — does not accept -h. Writing go -h or go --help is a very common beginner mistake that results in a flag error. You must use go help when you are not inside a subcommand.

How the Help Output Is Structured

Each help page follows a consistent layout that makes scanning for information predictable:

1. Header line — a one-sentence description (e.g., "Build compiles the packages named by the import paths...").
2. Usage line — the exact syntax, with brackets for optional parts.
3. Description — paragraphs explaining what the command does and any important default behaviors.
4. Flags — a list of every accepted flag, grouped by shared flags first, then command-specific ones.

The flag list is especially thorough. Flags that appear across multiple commands (like -v for verbose output, or -x to print executed commands) are documented once and identified as shared. This avoids duplication in the tool's internal documentation and helps you recognize patterns across different subcommands.

When a flag accepts a value, the help output shows the syntax inline — for example, -o output tells you that -o expects a following argument. Flags that are boolean toggles (on/off) do not take a value; -v simply means "verbose mode enabled."

Navigating the Help System Efficiently

The help system is hierarchical, and the fastest way to navigate it is to treat it as a tree:

• Start with go help to see the top-level commands and topic list.
• For a command, run go help <command>.
• If a concept appears in the output that you do not understand (like "build constraints"), use go help buildconstraint to read its dedicated page.

You rarely need to memorize more than a handful of commands because the tree itself serves as a live reference. Many experienced Go developers keep a terminal open and run go help as their first instinct when they encounter an unfamiliar subcommand.

Common Mistakes When Using Help

Mistakes with the go help system are easy to make but equally easy to fix once you know the rules.

Confusing the help subcommand with a help flag

The go binary has a help subcommand, not a -help flag. go -help fails. go help works. To get help for a specific subcommand, you can use either go help build or go build -h. The key is that at the top level, only the help subcommand is valid.

Assuming go help covers everything

The output of go help lists subcommands and additional help topics, but it does not show every possible flag for every command. You must drill down with go help <command> to see those. A developer who only ever runs go help and skims the summary will miss critical flags like -race or -cover that only appear in the detailed help for go test and go build.

Trying to get help for a non-existent command

Running go help nonexistent produces unknown help topic "nonexistent". The error message tells you exactly what went wrong, but it can be confusing if you expected the tool to guess or offer suggestions. There is no fuzzy matching. You need the exact subcommand or topic name from the go help listing.

How This Fits Into Daily Work

The go command's self-documenting nature means the terminal becomes a self-contained learning environment. When you are writing a build script or debugging a CI pipeline, the fastest answer is often go help <command> rather than a web search. Because the help is versioned with the Go toolchain itself, the information always matches the exact binary you are using — no risk of reading documentation for a newer or older version.

The help system also reflects the design philosophy of the go command: conventions over configuration. You cannot add custom help topics or flags to the built-in system, and that constraint keeps the documentation predictable. You learn the pattern once, and it applies across every subcommand.

As you progress through the rest of this chapter, each go subcommand will reference its help page as the authoritative source. The habit of running go help <command> before using a subcommand for the first time will save you from misusing flags and misunderstanding defaults.

Summary

The go command is a single binary that dispatches to subcommands, and its help system is the fastest way to discover what each subcommand can do. The syntax go help opens the top-level index; go help <command> and go help <topic> give detailed, version-accurate documentation. The built-in help replaces external man pages and web searches for most day-to-day questions about the Go toolchain.

The most important habit to build from this section is to run go help whenever you face an unfamiliar subcommand or an error related to flags or arguments. The answer you need is almost certainly already on your machine, structured in a consistent and searchable format.