
`flag.NewFlagSet` creates an independent flag parser. Dispatch on `os.Args[1]` to select the subcommand, then call `Parse` on the matching `FlagSet` with the remaining arguments.

<ExamplePair>
<ExampleProse>

Create a `FlagSet` for each subcommand. Each set parses only its own flags, so `--output` on `build` does not conflict with `--output` on `deploy`.

</ExampleProse>
<ExampleCode>

```go
package main

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

func main() {
    buildCmd := flag.NewFlagSet("build", flag.ExitOnError)
    buildOutput := buildCmd.String("output", "app", "output binary name")

    deployCmd := flag.NewFlagSet("deploy", flag.ExitOnError)
    deployEnv := deployCmd.String("env", "staging", "target environment")

    if len(os.Args) < 2 {
        fmt.Println("usage: tool <build|deploy> [flags]")
        os.Exit(1)
    }

    switch os.Args[1] {
    case "build":
        buildCmd.Parse(os.Args[2:])
        fmt.Printf("building binary: %s\n", *buildOutput)
    case "deploy":
        deployCmd.Parse(os.Args[2:])
        fmt.Printf("deploying to: %s\n", *deployEnv)
    default:
        fmt.Printf("unknown subcommand: %s\n", os.Args[1])
        os.Exit(1)
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Each `FlagSet` exposes its own `Args()` method returning positional arguments that follow the flags. Subcommand positional arguments do not mix with the top-level `os.Args`.

</ExampleProse>
<ExampleCode>

```go
package main

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

func main() {
    addCmd := flag.NewFlagSet("add", flag.ExitOnError)
    force := addCmd.Bool("force", false, "overwrite if exists")

    if len(os.Args) < 2 {
        fmt.Fprintln(os.Stderr, "usage: store <add> [flags] <files...>")
        os.Exit(1)
    }

    switch os.Args[1] {
    case "add":
        addCmd.Parse(os.Args[2:])
        files := addCmd.Args() // positional args after flags
        fmt.Printf("force: %v, files: %v\n", *force, files)
    default:
        fmt.Fprintf(os.Stderr, "unknown: %s\n", os.Args[1])
        os.Exit(1)
    }
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
The standard library `flag.FlagSet` approach is sufficient for tools with two or three subcommands. For larger CLIs (nested subcommands, shell completion, manpage generation, rich help formatting), cobra or urfave/cli are the production standard - they are what the Go, Docker, and Kubernetes CLIs use. Structure subcommands as separate packages to keep `main` thin: each subcommand package exports a `Run(args []string) error` function, and `main` dispatches to it. This makes subcommands independently testable without going through `os.Args`. Always handle the case where `os.Args` has fewer than two elements before indexing into `os.Args[1]` - a bare invocation without a subcommand should print usage and exit cleanly, not panic.
</InProduction>


flag.NewFlagSet creates a per-subcommand flag set, enabling tools with subcommands like "git commit" or "docker run" where each subcommand has its own flags.

Command-Line Subcommands


`os.Getenv` returns the value of an environment variable or an empty string if the variable is not set. `os.LookupEnv` returns a second boolean that tells you which case you have.

<ExamplePair>
<ExampleProse>

`os.Getenv` is the quick read. `os.LookupEnv` returns `(value, ok)` - use it when an empty string is a valid value and you need to distinguish it from an absent variable.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
)

func main() {
    // Simple read - empty string if not set
    home := os.Getenv("HOME")
    fmt.Println("HOME:", home)

    // Distinguish "not set" from "set to empty"
    val, ok := os.LookupEnv("MY_API_KEY")
    if !ok {
        fmt.Println("MY_API_KEY is not set")
    } else {
        fmt.Printf("MY_API_KEY = %q\n", val)
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`os.Environ` returns all environment variables as a `[]string` in `KEY=VALUE` form. `os.Setenv` and `os.Unsetenv` mutate the process environment - changes are visible to child processes spawned after the call.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
    "strings"
)

func main() {
    os.Setenv("APP_ENV", "production")
    defer os.Unsetenv("APP_ENV")

    // os.Environ returns all KEY=VALUE pairs
    for _, entry := range os.Environ() {
        if strings.HasPrefix(entry, "APP_") {
            fmt.Println(entry)
        }
    }

    // os.Expand substitutes ${VAR} references
    template := "running in ${APP_ENV} mode"
    fmt.Println(os.ExpandEnv(template))
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Use `os.LookupEnv` instead of `os.Getenv` when you need to distinguish "not set" from "set to empty string" - a blank `DATABASE_URL` and a missing `DATABASE_URL` are different failure modes. Parse and validate all required environment variables at startup and fail fast with a descriptive error: discovering a missing variable on the first request is worse than crashing on boot. A common pattern is a `config.Load()` function called in `main` that reads every required var with `LookupEnv`, collects all missing names into a slice, and returns a single error listing them all. Libraries like `kelseyhightower/envconfig` or `caarlos0/env` automate this: they populate a struct from env vars and validate required fields in one call. For secrets (database passwords, API keys), prefer a secrets manager (AWS Secrets Manager, HashiCorp Vault) that injects values as env vars at container start rather than baking them into images or config files.
</InProduction>


os.Getenv reads env vars; os.LookupEnv distinguishes "not set" from "set to empty string" - critical for required config validation at startup.

Environment Variables


The `flag` package parses named command-line flags. Declare flags before calling `flag.Parse()`, then access their values through the returned pointers or with `flag.Args()` for remaining positional arguments.

<ExamplePair>
<ExampleProse>

Declare typed flags with `flag.String`, `flag.Int`, `flag.Bool`, and `flag.Duration`. Each returns a pointer to the flag's value. Call `flag.Parse()` to process `os.Args[1:]` before reading any flag value.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "flag"
    "fmt"
)

func main() {
    host := flag.String("host", "localhost", "server hostname")
    port := flag.Int("port", 8080, "server port")
    verbose := flag.Bool("verbose", false, "enable verbose output")

    flag.Parse()

    fmt.Printf("host: %s\n", *host)
    fmt.Printf("port: %d\n", *port)
    fmt.Printf("verbose: %v\n", *verbose)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

After `flag.Parse()`, `flag.Args()` returns the remaining non-flag positional arguments. This lets a command accept both flags and positional arguments in any order.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "flag"
    "fmt"
)

func main() {
    output := flag.String("output", "stdout", "output destination")
    flag.Parse()

    positional := flag.Args()
    fmt.Printf("output: %s\n", *output)
    fmt.Printf("files:  %v\n", positional)
}
// Usage: ./tool --output=file.txt a.go b.go
// output: file.txt
// files:  [a.go b.go]
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Override `flag.Usage` to customize the help message shown for `-help` or `-h`. The default usage lists all flags alphabetically with their defaults and descriptions.

</ExampleProse>
<ExampleCode>

```go
package main

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

func main() {
    timeout := flag.Duration("timeout", 0, "request timeout (0 = no timeout)")

    flag.Usage = func() {
        fmt.Fprintf(os.Stderr, "Usage: fetch [flags] <url>\n\nFlags:\n")
        flag.PrintDefaults()
    }

    flag.Parse()

    if flag.NArg() == 0 {
        flag.Usage()
        os.Exit(1)
    }

    fmt.Printf("fetching %s (timeout: %v)\n", flag.Arg(0), *timeout)
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
The `flag` package is sufficient for single-command tools. Always set meaningful defaults and usage strings - they appear in the auto-generated `-help` output and are the primary documentation for most CLI tools. Always call `flag.Parse()` before reading any flag value; accessing a flag value before `flag.Parse()` returns the declared default, not the user-supplied value, which masks bugs silently. The `flag` package accepts both one- and two-dash forms: `-name value`, `-name=value`, `--name value`, and `--name=value` are all equivalent. What it does not support is combined short flags (`-abc` meaning `-a -b -c`) or positional-only GNU-style `--` termination; for those patterns use a third-party library like `pflag` or `cobra`. For integration tests of CLI tools, `flag.CommandLine` can be reset between calls, but it is generally cleaner to refactor the tool so the flag set is a parameter rather than global state.
</InProduction>


The flag package parses named flags (--name=value or --name value), generates help text automatically, and provides typed accessors for string, int, bool, and duration values.