Skip to main content

cli.arg

The cli.arg function declares one positional argument for a standalone program. Pass the declarations to cli.command, which parses the command line and delivers the values to your entry function.

Usage​

cli.arg(name, description = "", required = True)

Arguments​

name

Required. The argument name, which is also its key in the args dictionary and its placeholder in the usage line. Required arguments appear as <name> and optional ones as [name]. A name starts with a letter and contains only letters, digits, underscores, and hyphens.

description
(Optional) Help text for the argument.
required

(Optional) Defaults to True. Pass False for an argument the user may omit. An omitted optional argument has the value None.

Returns​

A declaration value for the args list of cli.command. The value has no other use on its own.

Examples​

#!/usr/bin/env atmos
def main(args, flags):
    region = args["region"] or "us-east-1"
    print("{} in {}".format(args["service"], region))

cli.command(
    run = main,
    args = [
        cli.arg("service", description = "Service name"),
        cli.arg("region", description = "Target region", required = False),
    ],
)
./deploy.star api
./deploy.star api us-west-2

Errors​

  • An invalid name fails with an argument error.
  • Declaring a required argument after an optional one fails when cli.command runs, because positional arguments fill from left to right.
  • Two arguments with the same name fail when cli.command runs. Names that differ only by case, such as Service and service, count as the same name.
  • On the command line, a missing required argument or an extra argument stops the program with a usage error before your functions run. The message names the argument, for example missing required argument `<service>` , and exits with status 2.

Related​