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:

--var myVariable=hello

Using Handlebars, you can refer to the variable in configuration files like so:

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

Or, if you prefer, EJS:

Resources:
  LogGroup:
    Type: AWS::Logs::LogGroup
    LogGroupName: <%= it.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:

--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:

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

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

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

And then with Handlebars, use the variable in the configuration like so:

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

Or like this when using EJS:

parameters:
  UserName: <%= it.var.person.name %>
  UserAge: <%= it.var.person.age %>

Example - Deserialize file contents to top-level variables#

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

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

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

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

And then with Handlebars, use the variables in the configuration like so:

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

Or, with EJS:

parameters:
  Color: <%= it.var.color %>
  FooBarEnabled: <%= it.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:

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

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

{
  "settings": {
    "debug": false
  }
}

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

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

The final merged variables object would look like this:

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