The go Command

Purpose and Scope

The go command is the main user-facing command in the Go toolchain. It is the command developers reach for to download dependencies, build packages and commands, install executables, run tests, and ask the toolchain for help. The official Go command documentation frames this as a deliberate design goal: Go programs should build from information already present in source files, especially package declarations and import paths, rather than from project-specific makefiles or large configuration systems. That convention-first model is the context for understanding every go subcommand.

This page is a reference-oriented overview rather than a tutorial. It explains how to think about the go command as a dispatcher, how built-in help and flags fit into Go’s command-line style, and how related toolchain commands appear when invoked through the Go distribution. The source paths supplied for this page do not include cmd/go itself, so the implementation details below use adjacent repository evidence: the vendored pprof driver used by go tool pprof, and a standard-library example that shows idiomatic CLI setup with flags, environment defaults, cancellation, and process exit behavior.

Sources: src/cmd/vendor/github.com/google/pprof/internal/driver/commands.go, src/cmd/vendor/github.com/google/pprof/internal/driver/cli.go, src/database/sql/example_cli_test.go

The important reader problem is practical orientation. A Go developer should know that go is not just a compiler executable. It is the coordination point for package loading, module-aware dependency resolution, building, testing, installation, and access to bundled tools. When a command needs lower-level functionality, the user still usually starts at go: for example, go test drives test compilation and execution, while go tool pprof exposes profile inspection through a bundled pprof command-line interface.

Relevant Source Files

• src/cmd/vendor/github.com/google/pprof/internal/driver/commands.go — Defines the pprof command table used by the bundled profiler UI, including command names, report formats, descriptions, usage text, parameter handling, extension hooks, and command help generation.
• src/cmd/vendor/github.com/google/pprof/internal/driver/cli.go — Parses pprof command-line flags, installs command-specific flags from the command table, prints usage text, recognizes profile sources, and chooses between immediate report generation and interactive use.
• src/database/sql/example_cli_test.go — Provides a standard-library example of a Go command-line program using flag, environment defaults, database/sql, context cancellation, signal handling, and explicit failure paths.

Command Model and Dispatch

At the user level, the go command is a dispatcher: the first word after go selects a task, and the remaining arguments are interpreted by that task. Common examples include go build, go test, go install, go run, go env, go list, go mod, go work, and go tool. The official documentation emphasizes that this model is built around conventions found in source code. Package names, imports, file suffixes, build constraints, module files, and workspace files tell the command what needs to happen without requiring a separate build script for ordinary projects.

The supplied pprof source shows a similar dispatch pattern at the level of a bundled tool. The commands type maps command names to command metadata, and each command records the report format, optional post-processing, optional visualization callback, whether a parameter is expected, a single-line description, and multi-line usage text. That table-driven shape is useful for readers because it mirrors the way Go tooling tends to present subcommands: commands are named, documented, selectable, and connected to behavior through structured metadata rather than ad hoc string handling.

Sources: src/cmd/vendor/github.com/google/pprof/internal/driver/commands.go

The pprof command table also illustrates how a tool can separate command selection from report generation. Entries such as comments, disasm, dot, list, peek, raw, tags, text, and top are not all parsed by independent front ends. They are entries in one command registry. Some commands require a function-name regular expression; others are simple switches. The same idea helps explain how developers should approach the go command: learn the top-level task first, then inspect that task’s help and flags rather than assuming every operation has the same arguments.

Built-in Help, Usage Text, and Flags

Good Go tools make their command-line surface discoverable. In the pprof driver, command.help constructs a help string from the command description and, when available, indented usage lines. The implementation keeps short descriptions and longer usage text together with the command definition. That makes help output part of the command contract, not a separate afterthought. For the go command, the user-facing equivalent is the family of help topics exposed through invocations such as go help, go help build, go help test, go help mod, and go help work.

Practical pattern: when a go command fails because of a flag, package pattern, module rule, or environment setting, start with the relevant go help topic before changing project layout.

Sources: src/cmd/vendor/github.com/google/pprof/internal/driver/commands.go

The pprof CLI also demonstrates how command-specific flags can be derived from registered commands. During flag parsing, the driver builds boolean flags for commands with no parameter and string flags for commands that need a parameter. This means the command registry directly affects the accepted CLI surface. It also prints a composed usage message that includes general usage, source syntax, extra flag usage, and configurable variables. The lesson for Go users is that command-line behavior is layered: there is global command selection, command-specific flag parsing, source or package arguments, and help text that explains the accepted combinations.

Sources: src/cmd/vendor/github.com/google/pprof/internal/driver/cli.go, src/cmd/vendor/github.com/google/pprof/internal/driver/commands.go

The database/sql CLI example provides a smaller example of standard Go flag behavior. It defines an id flag, a dsn flag whose default is read from the DSN environment variable, calls flag.Parse, and validates required inputs before continuing. Although this file is not part of cmd/go, it reflects the conventions Go developers see across repository examples: parse flags early, fail clearly for missing required data, keep environment-derived defaults explicit, and make the remaining program flow ordinary Go code.

Sources: src/database/sql/example_cli_test.go

Toolchain Integration: go tool and pprof

The go command is also the front door to lower-level tools shipped with the distribution. The most visible form is go tool name, where the go command locates and runs a tool from the installed toolchain. The supplied pprof files are relevant because pprof is one of the diagnostic tools exposed through this ecosystem. Its CLI supports profile sources, executable names or build identifiers, base and diff profiles, symbolization settings, timeouts, dynamic profile duration, output commands, and an optional HTTP web UI.

Sources: src/cmd/vendor/github.com/google/pprof/internal/driver/cli.go

In cli.go, parsed profile input is represented by a source structure. That structure records profile sources, executable name, build ID, base profiles, diff-base selection, normalization, timeout, symbolization mode, HTTP host and port, browser behavior, comments, and whether all frames should be retained. These fields describe the shape of a profiling command: first identify what profile data to inspect, then choose symbolization and comparison settings, then decide whether to generate a report or enter an interactive/web workflow.

The pprof parser recognizes many profiling flags before it chooses a report command. Comparison options such as diff_base and base alter how profiles are interpreted. Source options such as symbolize, buildid, timeout, add_comment, and all_frames affect fetching and presentation. Profile-kind options such as inuse_space, alloc_objects, total_delay, and contentions select sample interpretation. This is a concrete example of the broader Go toolchain pattern: a simple entry command can expose sophisticated behavior while keeping usage discoverable through flags and help.

API and CLI Surface Reference

Use this compact reference to orient yourself before reading a detailed help topic. The top-level go command selects a task, and the most common task categories are build execution, dependency and module management, workspace management, testing, environment inspection, package listing, and access to bundled tools. The official Go command article specifically calls out downloading, building, installation, and testing as automated responsibilities. In modern Go workflows, module and workspace subcommands are also central to how those tasks find and select source code.

Surface	What it is for	How to inspect it
go help	Index of built-in help topics	go help
go help <topic>	Detailed help for a command or concept	go help build, go help test, go help mod
go build	Compile packages or commands	go help build
go test	Compile and run tests, examples, benchmarks, and fuzz targets as supported by test flags	go help test
go install	Build and install commands or packages according to command semantics	go help install
go mod	Manage a module’s dependency metadata	go help mod
go work	Manage multi-module workspaces	go help work
go tool <name>	Run a bundled toolchain command, such as pprof	go tool, then tool-specific help

The supplied pprof API surface is smaller but concrete. AddCommand(cmd string, format int, post PostProcessor, desc, usage string) adds or replaces a pprof command, which allows extensions to register specialized visualization formats. SetVariableDefault(variable, value string) changes the default value for a pprof configuration variable. PostProcessor is a function type that reads report input, writes processed output, and can interact with the UI. These exported hooks show that even bundled tools can have extension seams while retaining a command-table contract.

Sources: src/cmd/vendor/github.com/google/pprof/internal/driver/commands.go

Execution Flow for a Command-Line Go Program

The database/sql example is useful because it shows what a complete command-line flow looks like once go run, go build, or an installed executable starts the program. The example parses flags, validates required input, opens a database handle with sql.Open, defers Close, configures connection pool limits, creates a cancellable root context, installs an interrupt signal handler, pings the database with a timeout, and then performs a parameterized query with its own timeout. This is idiomatic Go application structure, not special build-system behavior.

Sources: src/database/sql/example_cli_test.go

That distinction matters when learning the go command. The go command gets code compiled, tested, run, listed, installed, or analyzed; the resulting program is still responsible for its own runtime flags, environment variables, cancellation, I/O, and error handling. A common beginner confusion is to mix toolchain flags with application flags. In practice, flags before and after task boundaries can belong to different parsers. When in doubt, use go help for toolchain flags and the application’s own help or documentation for program flags.

Next Steps

If you are new to Go, first practice go run, go test, and go build in a small module so that command dispatch, package patterns, and test discovery become familiar. Then read the module and workspace pages to understand how the command chooses dependencies and source roots. If you are diagnosing performance, follow the pprof and diagnostics pages next; the pprof driver shown here is the implementation basis for a rich command surface that is normally reached through the Go toolchain.

Related pages: getting-started, build-and-install, testing, modules-overview, toolchain-command-reference, pprof