Command-Line Flags with the flag Package

A backup script runs from cron at 02:00. The source directory is /var/data, written directly into the source file because it never changes. In March the storage team mounts a new volume at /srv/data, and the only fix is an edit, a rebuild, and a redeploy of a program whose logic did not change at all. Every path, limit, and toggle hardcoded into a binary is a decision that will later need to be made by someone who cannot recompile it.

The flag package turns command-line arguments into typed values with defaults, and the whole API fits in four moves: declare, parse, check, use.

package main

import (
	"flag"
	"fmt"
	"os"
	"time"
)

func main() {
	src := flag.String("src", "", "directory to archive (required)")
	dest := flag.String("dest", "backup.tar", "archive output path")
	keep := flag.Int("keep", 30, "days to retain archives")
	verbose := flag.Bool("v", false, "print each file as it is added")
	timeout := flag.Duration("timeout", 30*time.Second, "max runtime for one pass")
	flag.Parse()

	if *src == "" {
		fmt.Fprintln(os.Stderr, "error: -src is required")
		flag.Usage()
		os.Exit(2)
	}

	deadline := time.Now().Add(*timeout)
	if err := archive(*src, *dest, *keep, *verbose, deadline); err != nil {
		fmt.Fprintln(os.Stderr, "backup:", err)
		os.Exit(1)
	}
}

Each constructor registers a flag — a name, a default, a usage string — and hands back a pointer to the storage it created. flag.Parse() reads os.Args[1:] and writes the parsed results through those pointers, so *keep is an int with no strconv.Atoi anywhere in your code. The default argument does double duty: it is what -keep prints as in the usage text and what the value equals when the flag is absent. Zero values never stand in for defaults — an omitted -keep means 30, not 0.

Three behaviors of flag.Parse() are worth memorizing because scripts depend on them:

• -h or -help prints the usage block and exits with status 0.
• An unknown flag prints the error, then the usage block, then exits with status 2.
• Parsing stops at the first argument that does not begin with -. Everything from there on lands in flag.Args().

That last rule produces the classic surprise: backup -src ./data report.txt -v sets src, then stops at report.txt, so verbose stays false and flag.Args() returns [report.txt -v]. The flag package does not support interspersed positionals. Put flags before operands, or document that your tool requires it.

Under the hood, flag.Parse walks a FlagSet — a registry mapping each name to a flag.Value. The typed constructors are just conveniences over that interface, and the registry explains the whole error surface: an unknown flag is a map miss, a bad value is a failing Set call, and a duplicate registration panics with flag redefined — which you will meet the first time two helpers both define verbose on the same set.

The deployment tool is growing: ship build, ship push, ship rollback. Each verb wants different flags — -tag means something different to build and to push — and a single flat flag list would drown the usage text. Third-party CLI frameworks solve this, but the standard library already does: one flag.FlagSet per verb, dispatched from os.Args[1].

func buildCmd(args []string) error {
	fs := flag.NewFlagSet("ship build", flag.ContinueOnError)
	tag := fs.String("tag", "", "image tag to build (required)")
	platform := fs.String("platform", "linux/amd64", "target platform")
	if err := fs.Parse(args); err != nil {
		return err
	}
	if *tag == "" {
		return fmt.Errorf("build: -tag is required")
	}
	return build(*tag, *platform)
}

func main() {
	if len(os.Args) < 2 {
		usage()
		os.Exit(2)
	}

	var err error
	switch verb, rest := os.Args[1], os.Args[2:]; verb {
	case "build":
		err = buildCmd(rest)
	case "push":
		err = pushCmd(rest)
	case "rollback":
		err = rollbackCmd(rest)
	default:
		err = fmt.Errorf("unknown command %q", verb)
	}
	if err != nil {
		if errors.Is(err, flag.ErrHelp) {
			os.Exit(0)
		}
		fmt.Fprintln(os.Stderr, "ship:", err)
		os.Exit(1)
	}
}

Two decisions carry the weight here.

ContinueOnError, not ExitOnError. The package-level functions operate on flag.CommandLine, whose error mode is ExitOnError: a bad flag terminates the process from inside the library. In a subcommand you want the parse error returned so main decides the exit code and the message format. ContinueOnError returns flag.ErrHelp when the user typed -h, which is why the switch above treats it as success — help is not a failure, and a script checking $? should see 0.

The verb is stripped before parsing. buildCmd receives os.Args[2:], so ship build -tag v3 never makes build look like a positional argument. Inside, fs.Args() returns whatever non-flag tokens followed the flags — the natural place for a path operand, which Files, Buffers, and Paths then teaches you to open, stream, and validate.

Shared flags across verbs (say, -verbose on everything) do not need to be declared five times. A small struct registers itself into any set:

type common struct {
	verbose bool
}

func (c *common) register(fs *flag.FlagSet) {
	fs.BoolVar(&c.verbose, "verbose", false, "print extra detail")
}

Each command creates its own set, calls common.register(fs), and reads c.verbose after parsing. Because each verb owns a private registry, there is no redefinition panic and no collision between -tag meanings.

One trap remains: flags that two commands share but parse differently (a -timeout read as seconds in one and milliseconds in another) are a bug waiting for a reader. Keep shared flags registered through one helper so their meaning has a single home.

An operator sets SHIP_PORT=9090 in the orchestrator. A developer runs the same binary locally with -port 3000. The README promises command line beats environment beats default — but the flag package knows nothing about environment variables, so the ordering is your code's job. The piece of the API you need is fs.Visit, which invokes a callback only for flags that were actually given on the command line (contrast fs.VisitAll, which walks every registered flag).

func resolvePort(fs *flag.FlagSet, flagPort *int) (int, error) {
	// Layer 1: default, baked into the flag declaration.
	port := 8080

	// Layer 2: environment, applied only if valid.
	if v, ok := os.LookupEnv("SHIP_PORT"); ok {
		n, err := strconv.Atoi(v)
		if err != nil {
			return 0, fmt.Errorf("SHIP_PORT must be an integer, got %q", v)
		}
		port = n
	}

	// Layer 3: command line, applied only if the flag was present.
	fs.Visit(func(f *flag.Flag) {
		if f.Name == "port" {
			port = *flagPort
		}
	})
	return port, nil
}

Reading the layers top to bottom reproduces the documented precedence: every later layer may overwrite the earlier one, but only when it has something to say. Note that a malformed environment variable is an error, not a shrug — silently falling back to a default after a typo hides the operator's intent and hands you a production incident with a wrong port.

When a flag's value needs validation or repeats, implement flag.Value yourself. The interface is two methods:

type stringList []string

func (l *stringList) String() string { return strings.Join(*l, ",") }

func (l *stringList) Set(s string) error {
	switch s {
	case "dev", "staging", "prod":
		*l = append(*l, s)
		return nil
	default:
		return fmt.Errorf("unknown environment %q (dev, staging, prod)", s)
	}
}

var envs stringList
fs.Var(&envs, "env", "target environment, repeatable")

Set runs during fs.Parse, so -env qa fails before the program does any work, with the message printed next to the usage block. String feeds flag.PrintDefaults, which is why returning the joined list shows a sensible default in help text. Repeatable flags fall out naturally: every occurrence calls Set again and appends.

Finally, exit codes are part of the contract. The flag package already exits 2 on a bad flag, so match it: 0 for success, 1 for a runtime failure the caller might retry, 2 for a usage error the caller must fix. A wrapper script that runs ship build -tag v3 || ship rollback is relying on that distinction to tell "the build broke" from "you typed the flag wrong." Error values stay ordinary Go values until the boundary — wrap them with %w as described in The error Interface and Error Messages — and let main translate them into a code once.