# cli.arg

The `cli.arg` function declares one positional argument for a standalone program. Pass the declarations to
[`cli.command`](/functions/automation/cli.command), which parses the command line and delivers the values to
your entry function.

## Usage

```python
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`](/functions/automation/cli.command). The value has no
other use on its own.

## Examples

```python
#!/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),
    ],
)
```

```shell
./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

- [`cli.command`](/functions/automation/cli.command) parses the declared arguments.
- [`cli.flag`](/functions/automation/cli.flag) declares named options.
- [Standalone CLI apps](/automation/standalone-cli-apps)