Golang Command Line Arguments: os.Args, flag and Env Vars

os.Args

os.Args is a slice of strings. os.Args[0] is the program's name, the rest are the arguments exactly as the shell passed them.

package main

import (
	"fmt"
	"os"
)

func main() {
	fmt.Println("argument count:", len(os.Args)-1)
	for i, arg := range os.Args[1:] {
		fmt.Printf("arg %d: %q\n", i+1, arg)
	}
	if len(os.Args) < 2 {
		fmt.Println("no arguments: type some in the Args panel and run again")
	}
}

In the editor's Args panel, each field is one argument, passed as is. Try hello, two words and -v in three fields: the program sees three arguments, and two words stays one argument with a space inside. In a terminal the shell does the splitting, so the same thing is go run . hello "two words" -v.

Always check len(os.Args) before indexing. os.Args[1] with no arguments panics with index out of range [1] with length 1.

Arguments are strings. Convert numbers with strconv.Atoi or strconv.ParseFloat and handle the error, since users type anything.

The flag package

For options like -port 8080 -verbose, use flag. It parses, converts types, reports errors and generates a help message.

package main

import (
	"flag"
	"fmt"
	"strings"
	"time"
)

func main() {
	name := flag.String("name", "world", "who to greet")
	count := flag.Int("count", 1, "how many times")
	loud := flag.Bool("loud", false, "shout the greeting")
	delay := flag.Duration("delay", 0, "pause between greetings, e.g. 10ms")

	flag.Parse()

	msg := "hello, " + *name
	if *loud {
		msg = strings.ToUpper(msg) + "!"
	}
	for i := range *count {
		if i > 0 {
			time.Sleep(*delay)
		}
		fmt.Println(msg)
	}
	fmt.Println("remaining args:", flag.Args())
}

With no arguments this prints hello, world once. In the Args panel, try -name and Gopher in two fields, then -count=3, -loud and extra as three more. The program prints HELLO, GOPHER! three times and remaining args: [extra].

How flags work:

• Each definer (flag.String, flag.Int, flag.Bool, flag.Float64, flag.Duration, flag.Uint64...) takes a name, a default and a usage string, and returns a pointer. Read the value with *name after flag.Parse().
• The Var forms bind to a variable you already have: flag.IntVar(&cfg.Port, "port", 8080, "port"). That is tidier for a config struct.
• Users can write -name value, -name=value, --name value or --name=value. Go makes no distinction between one and two dashes.
• Booleans need = to take a value. -loud sets true, -loud=false sets false, but -loud false sets true and leaves false as a positional argument.
• Parsing stops at the first non-flag argument (or at --). prog file.txt -v treats -v as a positional argument. Put flags first.
• flag.Args() returns the positional arguments that remain, flag.NArg() their count, and flag.Arg(i) one of them.

An unknown flag or a bad value prints an error plus the usage, and exits with status 2. -h or -help prints the usage and exits with status 0 (since Go 1.15). The usage text is generated from your definitions:

Usage of greet:
  -count int
    	how many times (default 1)
  -delay duration
    	pause between greetings, e.g. 10ms
  -loud
    	shout the greeting
  -name string
    	who to greet (default "world")

Set flag.Usage to a function to print your own header before calling flag.PrintDefaults().

Subcommands with FlagSet

Tools like git commit -m msg have subcommands with their own flags. Create a flag.FlagSet per subcommand and pick one with a switch on the first argument:

package main

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

func run(args []string) error {
	if len(args) < 1 {
		return fmt.Errorf("usage: todo <add|list> [flags]")
	}

	switch args[0] {
	case "add":
		fs := flag.NewFlagSet("add", flag.ContinueOnError)
		priority := fs.Int("p", 3, "priority 1 to 5")
		if err := fs.Parse(args[1:]); err != nil {
			return err
		}
		if fs.NArg() == 0 {
			return fmt.Errorf("add: missing task text")
		}
		fmt.Printf("added %q with priority %d\n", fs.Arg(0), *priority)
	case "list":
		fs := flag.NewFlagSet("list", flag.ContinueOnError)
		all := fs.Bool("all", false, "include finished tasks")
		if err := fs.Parse(args[1:]); err != nil {
			return err
		}
		fmt.Println("listing tasks, all =", *all)
	default:
		return fmt.Errorf("unknown command %q", args[0])
	}
	return nil
}

func main() {
	args := os.Args[1:]
	if len(args) == 0 {
		args = []string{"add", "-p", "1", "buy milk"} // demo input when the Args panel is empty
	}
	if err := run(args); err != nil {
		fmt.Fprintln(os.Stderr, "error:", err)
		os.Exit(1)
	}
}

flag.ContinueOnError makes Parse return an error instead of exiting, which keeps the function testable. run takes the arguments as a parameter rather than reading os.Args, so a test can call run([]string{"list", "-all"}) directly. Try list and -all in the Args panel, or delete to see the error path.

For large CLIs with nested commands, shell completion and generated docs, most projects use the third-party github.com/spf13/cobra. The standard flag package covers small tools well.

Environment variables

package main

import (
	"fmt"
	"os"
	"strconv"
)

func envInt(key string, fallback int) (int, error) {
	v, ok := os.LookupEnv(key)
	if !ok {
		return fallback, nil
	}
	n, err := strconv.Atoi(v)
	if err != nil {
		return 0, fmt.Errorf("%s must be a number, got %q", key, v)
	}
	return n, nil
}

func main() {
	os.Setenv("APP_WORKERS", "8") // for the demo; normally set by the shell
	os.Setenv("APP_MODE", "")     // set, but empty
	os.Unsetenv("APP_MISSING")    // make sure it is unset

	fmt.Printf("Getenv APP_MODE:    %q\n", os.Getenv("APP_MODE"))
	fmt.Printf("Getenv APP_MISSING: %q\n", os.Getenv("APP_MISSING"))

	_, modeSet := os.LookupEnv("APP_MODE")
	_, missingSet := os.LookupEnv("APP_MISSING")
	fmt.Println("APP_MODE set:", modeSet, "| APP_MISSING set:", missingSet)

	workers, err := envInt("APP_WORKERS", 4)
	fmt.Println("workers:", workers, err)

	timeout, err := envInt("APP_TIMEOUT", 30)
	fmt.Println("timeout:", timeout, err)

	fmt.Println(os.ExpandEnv("running with $APP_WORKERS workers"))
}

• os.Getenv returns "" both when the variable is missing and when it is set to an empty string. os.LookupEnv tells them apart.
• Values are always strings. Convert and validate them at startup, and fail with a clear message rather than halfway through a request.
• os.Setenv affects the current process and child processes started later. It cannot change the environment of the shell that launched you.
• os.Environ() returns all variables as "KEY=value" strings.

A common layout for configuration: flags for things a person types, environment variables for deployment settings (container platforms set them), with flags overriding the environment and the environment overriding defaults.

Exit codes and os.Exit

A Go program exits with status 0 when main returns. os.Exit(code) ends the process immediately with that status. By convention 0 is success, 1 a general error, and 2 a usage error (the flag package uses 2).

os.Exit does not run deferred functions. Files are not flushed and defer cleanup is skipped. log.Fatal calls os.Exit(1) and has the same effect. Keep os.Exit in one place, at the end of main, and put the real program in a run function that returns an error, as the subcommand example does:

func main() {
	if err := run(os.Args[1:]); err != nil {
		fmt.Fprintln(os.Stderr, "error:", err)
		os.Exit(1)
	}
}

Write error messages to os.Stderr, not os.Stdout, so they stay visible when output is redirected to a file or piped to another command. A panic that is not recovered exits with status 2.

Common mistakes

• Indexing os.Args without checking its length. Missing arguments panic.
• Reading flags before flag.Parse(). You get the defaults.
• Forgetting the *. fmt.Println(port) prints an address like 0xc000012345, not the value.
• Putting flags after positional arguments. prog input.txt -v does not parse -v.
• -verbose false for a bool flag. Write -verbose=false.
• Calling os.Exit or log.Fatal deep inside the program. Deferred cleanup never runs and the code cannot be tested. Return errors up to main.