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:
- Explicit parameter flags provided on the command-line
- Environment variables defined in the shell *
- Parameter flags defined in the
.stackery-config.yaml
file of the current directory - Parameter flags defined in the
.stackery-config.yaml
file that exists in a parent directory (up to root directory) - 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
.stackery-config.yaml
Defining parameters in 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 currentsrc/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.