Skip to main content

cli.flag

The cli.flag function declares one typed flag for a standalone program. Pass the declarations to cli.command, which parses the command line, applies defaults and environment bindings, and delivers typed values to your entry function.

Usage​

cli.flag(
    name,
    type = "string",
    default = None,
    shorthand = "",
    description = "",
    required = False,
    choices = [],
    env = "",
)

Arguments​

name

Required. The flag name without dashes, which is also its key in the flags dictionary. The user passes it as --name. A name starts with a letter and contains only letters, digits, underscores, and hyphens. The name help is reserved, and names are case-insensitive, so Stage and stage cannot both be declared.

type

(Optional) One of "string" (the default), "int", "bool", or "string_list". The value arrives in the flags dictionary as a string, an integer, a boolean, or a list of strings.

default

(Optional) The value used when the flag is not supplied. It must match the flag type: a string, an integer that fits a native integer, a boolean, or a list or tuple of strings. Without a default, a string flag is "", an integer flag is 0, a boolean flag is False, and a list flag is an empty list.

shorthand
(Optional) A single letter, other than h, that lets the user pass -r instead of --replicas.
description
(Optional) Help text for the flag.
required

(Optional) Defaults to False. A required flag must be supplied on the command line or through its env binding. A required flag cannot declare a default, and boolean flags cannot be required.

choices

(Optional) A list or tuple of allowed strings. Choices apply to string and string_list flags. A value outside the list stops the program with an error that names the valid values. A declared default must be one of the choices, otherwise cli.flag fails when the script is loaded. An empty value typed on the command line (--stage=) is checked against the choices like any other value.

env

(Optional) The name of an environment variable that supplies the value when the flag is not on the command line. The first non-empty value wins. Command-line values override the environment, which overrides the default. Environment values parse exactly like command-line values: a string_list splits on commas with CSV quoting (TAGS=a,b is ["a", "b"]) and an int accepts base-10 digits only. With choices, every list element is checked.

Returns​

A declaration value for the flags list of cli.command.

Command-line forms​

  • The forms --replicas=3, --replicas 3, and -r 3 set an integer or string flag.
  • The form --verbose sets a boolean flag to True, and --verbose=false sets it to False. A boolean flag never consumes the next word, so --verbose false is rejected with a hint to write --verbose=false.
  • An int flag reads base-10 digits only. --count 010 is ten, and --count 0x10 is an error.
  • When the same flag appears more than once on the command line, the last value wins (--stage=dev --stage=prod is prod). Only a string_list flag collects every occurrence.
  • A string_list flag accepts comma-separated values, repeated flags, or both: --tag=a,b --tag=c produces ["a", "b", "c"].

Examples​

#!/usr/bin/env atmos
def main(args, flags):
    print(flags["replicas"], flags["environment"], flags["tag"], flags["verbose"])

cli.command(
    run = main,
    flags = [
        cli.flag("replicas", type = "int", shorthand = "r", default = 2,
                 description = "Number of replicas"),
        cli.flag("environment", choices = ["dev", "prod"], default = "dev",
                 env = "DEPLOY_ENV"),
        cli.flag("tag", type = "string_list", shorthand = "t"),
        cli.flag("verbose", type = "bool"),
    ],
)
./deploy.star --replicas=5 --tag=blue,green --verbose
5 dev ["blue", "green"] True

Errors​

  • An invalid name, an invalid shorthand, an unsupported type, or a default of the wrong type fails with an argument error when cli.flag is called.
  • Setting choices on an int or bool flag fails, and so does a default that is not one of the choices.
  • Duplicate flag names or shorthands in one cli.command call fail, and names that differ only by case count as duplicates.
  • A missing required flag, an unknown flag, an invalid value, or a value outside choices stops the program with a usage error before your functions run. A usage error has no traceback, suggests --help, and exits with status 2.

Help output​

--help prints the usage and then ends the script: nothing after the cli.command call runs, and the exit status is 0.

--help annotates each flag: (required) for a required flag, (one of: dev, prod) for choices, and [env: DEPLOY_ENV] for an env binding, for example --environment string (one of: dev, prod) [env: DEPLOY_ENV] (default "dev").

Related​