# Command-line variables

You can pass variables from command line using `--var` and `--var-file` options. Both options can be used multiple times. Variables are exposed via `var` variable.

## Named variables

Use `--var` option to pass a single named variable from the command line.

#### Example

Provide a single variable named **myVariable** with value **hello**:

```bash
--var myVariable=hello
```

You can refer to the variable in configuration files like so:

```yaml
Resources:
  LogGroup:
    Type: AWS::Logs::LogGroup
    LogGroupName: {{ var.myVariable }}
```

## Variables from files

Use `--var-file` option to load variables from a file. If the file extension is **.json** or **.yml**, the file is first parsed into an object which is then stored to a variable. If the file extension is something else, the contents are just read into a variable.

The variable name can be omitted for **.yml** and **.json** files as long as the file contents can be deserialized to an object. The deserialized object is then stored to the top-level of variables.

#### Example - Read file contents to a variable

If the project directory contains a file named **commit.txt**, you can read its contents into a variable named **commitHash** like so:

```bash
--var-file commitHash=commit.txt
```

#### Example - Deserialize file contents to a variable

Here's an example how you would deserialize file contents to a variable. Suppose you have a file **/home/variables.yml** with valid YAML contents:

{% code title="/home/variables.yml" %}

```yaml
name: James
age: 55
permissions:
  - create
  - delete
  - update
```

{% endcode %}

You can deserialize its contents to a variable named **myVariable** like so:

```bash
--var-file person=/home/variables.yml
```

And then use the variable in the configuration like so:

```yaml
parameters:
  UserName: {{ var.person.name }}
  UserAge: {{ var.person.age }}
```

#### Example - Deserialize file contents to top-level variables

Say, you have a file **properties.json** with valid JSON contents:

{% code title="properties.json" %}

```yaml
{
  "color: "red",
  "foo": {
    "bar": true
  }
}
```

{% endcode %}

You can deserialize its contents to top-level of variables:

```bash
--var-file person=/home/variables.yml
```

And then use the variables in the configuration like so:

```yaml
parameters:
  Color: {{ var.color }}
  FooBarEnabled: {{ var.foo.bar }}
```

## Loading order and merging of variables

Variables from files are loaded first in the order they are defined, and then the named variables also in the definition order. Variables defined later will override previously loaded variables with the same name. Complex variables are merged recursively.

#### Example

Say, you have a JSON file that defines some basic settings:

{% code title="base.json" %}

```yaml
{
  "color": "blue",
  "width": 100,
  "settings": {
    "debug": true
  }
}
```

{% endcode %}

You also have another file that contains environment-specific settings:

{% code title="prod.json" %}

```yaml
{
  "settings": {
    "debug": false
  }
}
```

{% endcode %}

You can load both settings files and also override and extend the loaded configuration using named variables:

```bash
--var-file base.json \
  --var-file prod.json \
  --var color=yellow \
  --var height=200
```

The final merged variables object would look like this:

```yaml
{
  "color": "yellow",
  "width": 100,
  "height": 200,
  "settings": {
    "debug": false
  }
}
```