Flags

This guide covers a Command's flags. You will learn how to:

• Declare flags of any type
• Pass flag values on the command line
• Add a short name for a flag
• Read a flag from an environment variable
• Accept a flag more than once
• Tell which flags were passed

Overview

Flags are the named options of a Command, such as --limit 5 or --force. A Command declares them in its Flags function, each bound to a variable that Run reads. Help lists them with their types and defaults, and an unknown flag is a usage error with a suggestion.

Flags receives a *cli.FlagSet, which is the standard library's flag.FlagSet with two additions, Alias and Env. Every flag type it offers works.

Declare flags

Declare each flag with its name, default and usage, and read the variable in Run:

func previewCommand() *cli.Command {
	var (
		port    int
		host    string
		open    bool
		timeout time.Duration
	)
	return &cli.Command{
		Name: "preview",
		Flags: func(f *cli.FlagSet) {
			f.IntVar(&port, "port", 3000, "The port to listen on")
			f.StringVar(&host, "host", "localhost", "The host to listen on")
			f.BoolVar(&open, "open", false, "Open the browser")
			f.DurationVar(&timeout, "timeout", 30*time.Second, "How long to wait for a request")
		},
		Run: func(ctx context.Context, c *cli.Call) (cli.Result, error) {
			…
		},
	}
}

$ act preview --help
Usage:
  act preview [flags]

Flags:
      --host string       The host to listen on (default localhost)
      --open              Open the browser
      --port int          The port to listen on (default 3000)
      --timeout duration  How long to wait for a request (default 30s)
  -h, --help              Show help
      --json              Print a single JSON result instead of text
      --no-interaction    Never prompt; use defaults

TextVar declares a flag of any type that parses itself from text, such as netip.Addr or a type of your own. A value that doesn't parse is a usage error naming the flag.

Pass flag values

A flag's value follows it, after a space or an equals sign. A bool flag needs no value, and takes one only after an equals sign:

act preview --port 8080 --open
act preview --port=8080 --open=false

Flags may come before or after the Command's arguments, and everything after -- is an argument.

Add a short name

Alias gives a flag another name. Both set the same variable, and help shows them together. Declare the flag first:

			f.BoolVar(&open, "open", false, "Open the browser")
			f.Alias("open", "o")

act preview -o

Read flags from the environment

Env lets an environment variable set a flag that the command line doesn't. The command line wins, then the variable, then the flag's default. Help shows the variable:

			f.IntVar(&port, "port", 3000, "The port to listen on")
			f.Env("port", "PORT")

      --port int          The port to listen on (default 3000) [$PORT]

The variable's value is checked like one typed on the command line: PORT=eighty is a usage error that names PORT.

Accept a flag more than once

Func calls a function for each occurrence, so a flag can collect values:

			var origins []string
			f.Func("origin", "Allow requests from this origin (repeatable)", func(s string) error {
				origins = append(origins, s)
				return nil
			})

act preview --origin https://example.com --origin https://admin.example.com

Tell which flags were passed

c.Given reports whether the command line, or an environment variable, set any of the flags named, or, with no names, any flag at all. Use it to tell a default from a value someone chose:

			if !c.Given("port") {
				c.Info("Listening on the default port, %d", port)
			}

Check flag values

A flag that must be in a range, or depends on another, is checked in Run. Return cli.UsageError so the Command exits with status 2 and points to its help:

			if port < 1 || port > 65535 {
				return nil, cli.UsageError("--port must be between 1 and 65535, got %d", port)
			}

To require a flag, ask for it with a prompt and cli.Required(): a person is asked, and a script that leaves it out gets an error naming the flag.

Flags every Command has

--helpbool

Shows the Command's help instead of running it. -h is the same.

--jsonbool

Prints a single JSON result. See Agent mode.

--no-interactionbool

Never prompts: answers come from flags and defaults. See Prompts.

See also: Arguments, Prompts, Creating Commands