Configuring the Stackery CLI

The Stackery CLI can retrieve default parameter flags from a configuration file or from environment variables you define. Available in Stackery CLI Version 2.7.0~. Before you continue, be sure to have the latest version of the Stackery CLI installed.

Defining CLI parameters

Default parameters can be registered in the .stackery-config.yaml file of a directory. If no argument or environment variable is passed into a CLI command, the CLI will search the current directory for a .stackery-config.yaml file for applicable flags. If the current directory does not have a .stackery-config.yaml file of its own, the CLI will continue upwards towards the root directory in search of any .stackery-config.yaml files in parent directories. Default parameters defined in parent directories, and not overridden, are used to populate the CLI command arguments.

Default parameters defined in this config file of a directory will automatically apply to commands that you run in any of its sub-directories. These values can be overridden by defining the same flags with different values in a sub-directory's own config file, or by passing the flags in the command-line directly.

Order of Precedence

The Stackery CLI follows this order of precedence when determining which values to use:

1. Explicit parameter flags provided on the command-line
2. Environment variables defined in the shell *
3. Parameter flags defined in the .stackery-config.yaml file of the current directory
4. Parameter flags defined in the .stackery-config.yaml file that exists in a parent directory (up to root directory)
5. Defaults defined by the Stackery CLI command

* Environment variables defined in the shell must be upper-case and use underscores in place of dashes e.g. STACKERY_STACK_NAME=MyStackName

Defining parameters in .stackery-config.yaml

We'll use the following project MessagingStack as an example, using the stackery local invoke command:

MessagingStack
  ├── src
      └── SendMessage
            ├── index.js
            ├── package.json
            ├── .stackery-config.yaml // Applies to CLI commands within `SendMessage` dir
            └── README.md
      └── RetrieveMessage
            ├── index.js
            ├── package.json
            ├── .stackery-config.yaml // Applies to CLI commands within `RetrieveMessage` dir
            └── README.md
  ├── template.yaml
  └── .stackery-config.yaml // Default parameters for all directories in project repository

The stackery local invoke command requires the stack-name, env-name, and function-id arguments. Defining CLI default parameters in a .stackery-config.yaml file of certain directories allows us to simplify this command.

In each function directory, a .stackery-config.yaml file will define the function-id to be used when stackery local invoke is run in either the SendMessage or RetrieveMessage directories.

The .stackery-config.yaml in the root directory will define the stack-name and env-name defaults that will apply to all CLI commands that require those flags unless they are overridden.

MessagingStack/src/SendMessage/.stackery-config.yaml

function-id: SendMessage

MessagingStack/src/RetrieveMessage/.stackery-config.yaml

function-id: RetrieveMessage

MessagingStack/.stackery-config.yaml

stack-name: MessagingStack
env-name: development

Running stackery local invoke in src/SendMessage

$ stackery local invoke

Since no command-line arguments or environment variables have been provided, the Stackery CLI checks the current directory's config file (src/SendMessage/.stackery-config.yaml) for default parameters. After retrieving the default function-id defined, it moves up the directory tree to the root directory's config file (MessagingStack/.stackery-config.yaml) and retrieves the default stack-name and env-name, resulting in the following command being run:

$ stackery local invoke --stack-name=MessagingStack --env-name=development --function-id=SendMessage

To test the SendMessage function the staging envrionment, you can either update the value env-name in src/SendMessage/.stackery-config.yaml, or override the default value manually by passing the --env-name=<ENV NAME> flag directly to the local invoke command.

In the directory, src/SendMessage:

$ stackery local invoke --env-name=staging

Defining parameters using environment variables

Another option for setting default parameters for your Stackery CLI commands is the use of environment variables. The parameter used in the previous example for the stack environment name (--env-name) can be set for that current directory by running the following:

In the directory, src/SendMessage:

$ export STACKERY_ENV_NAME=staging

Now, when you run stackery local invoke, the Stackery CLI will retrieve your parameter values

• --env-name from the environment variable defined on the command-line
• --function-id from the config file in current src/SendMessage directory
• --stack-name from .stackery-config.yaml in the root directory

CLI parameters are retrieved following the order of precedence; parameter flag or environment variables on the command line, followed by parameters set in the current directory config file, and finally the config file in the root directory of the SendMessage project.

Defining file path parameters

In .stackery-config.yaml, file paths that point to other project files, such as template.yaml in the root directory, need to be relative to the current directory.

We'll go through another example by revisiting the MessagingStack we worked with previously:

MessagingStack
  ├── src
      └── SendMessage
            ├── index.js
            ├── package.json
            ├── .stackery-config.yaml // Applies to CLI commands within `SendMessage` dir
            └── README.md
      └── RetrieveMessage
            ├── index.js
            ├── package.json
            ├── .stackery-config.yaml // Applies to CLI commands within `RetrieveMessage` dir
            └── README.md
  ├── template.yaml
  └── .stackery-config.yaml // Default parameters for all directories in project repository

Let's say the root directory's .stackery-config.yaml file contains the following:

stack-name: MessagingStack
env-name: development
template-path: ./template.yaml

And the .stackery-config.yaml file in src/SendMessage contains the following:

function-id: SendMessage

If you to run the $ stackery local invoke with no flags, from within thesrc/SendMessage directory, you'll receive a file not found error.

Since it's run within src/SendMessage, no parameters are passed on the command line, and no template-path value is defined in the current directory's config file, the Stackery CLI defaulted to the .stackery-config.yaml file all the way up in the root directory.

In this example, the CLI uses ./template.yaml as the template file path while running stackery local invoke in a project sub-directory, and fails to locate it.

Based on the directory tree, the correct template path and .stackery-config.yaml file in the src/SendMessage directory should look like this:

function-id: SendMessage
template-path: ../../template.yaml

Keep this in mind when specifying file paths as default parameter values for the Stackery CLI.