
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.

Command-Line Flags


`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.Args` is a `[]string` containing the raw command-line arguments. `os.Args[0]` is the path to the running binary; `os.Args[1:]` contains everything the user typed after the binary name.

<ExamplePair>
<ExampleProse>

Access `os.Args` directly for simple tools that take positional arguments. The slice is always non-nil - when no arguments are given, `os.Args` has length 1 (just the binary name).

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
)

func main() {
    args := os.Args

    fmt.Println("binary:", args[0])
    fmt.Println("args:  ", args[1:])
    fmt.Println("count: ", len(args)-1)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Check argument count before indexing to avoid an index-out-of-range panic. Access individual arguments by index after validating length.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
)

func main() {
    if len(os.Args) < 2 {
        fmt.Fprintln(os.Stderr, "usage: greet <name>")
        os.Exit(1)
    }

    name := os.Args[1]
    fmt.Printf("Hello, %s!\n", name)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Iterate over all provided arguments with a range loop over `os.Args[1:]`.

</ExampleProse>
<ExampleCode>

```go
package main

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

func main() {
    args := os.Args[1:]

    if len(args) == 0 {
        fmt.Println("no arguments provided")
        return
    }

    fmt.Println("joined:", strings.Join(args, ", "))

    for i, arg := range args {
        fmt.Printf("  [%d] %s\n", i, arg)
    }
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
`os.Args` is appropriate for positional arguments in simple, single-purpose tools. For anything with optional flags (`--verbose`, `--output=file`), use the `flag` package - it generates consistent help text and handles the `--` convention automatically. For tools with subcommands (`git commit`, `docker run`), use `flag.FlagSet` per subcommand or a library like cobra. Parsing `os.Args` by hand for complex CLIs produces fragile code that fails on edge cases (arguments with spaces, `--` end-of-flags, `-` as stdin indicator) that users expect to work. Never use `os.Args[0]` to infer the install location of the binary at runtime - use `os.Executable()` instead, which resolves symlinks.
</InProduction>


os.Args provides raw access to command-line arguments as a string slice, with os.Args[0] holding the binary name and os.Args[1:] holding the user-supplied arguments.