Configuring the AWS SAM CLI - AWS Serverless Application Model

Configuring the AWS SAM CLI

Configure credentials, basic settings, and project settings for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI).

Configure credentials and basic settings

Use the AWS Command Line Interface (AWS CLI) to configure basic settings such as AWS credentials, default region name, and default output format. Once configured, you can use these settings with the AWS SAM CLI. To learn more, see the following from the AWS Command Line Interface User Guide:

For quick setup instructions, see Step 5: Use the AWS CLI to configure AWS credentials.

Configure project settings

You can specify project-specific settings, such as AWS SAM CLI command parameter values, in a configuration file to use with the AWS SAM CLI. For more information about this configuration file, see AWS SAM CLI configuration file.

Using configuration files

Configuration files are structured by environment, command, and parameter value. For more information, see Configuration file basics.

To configure a new environment
  1. Specify your new environment in your configuration file.

    The following is an example of specifying a new prod environment:

    TOML
    [prod.global.parameters]
    YAML
    prod: global: parameters:
  2. Specify parameter values as key-value pairs in the parameters section of the configuration file.

    The following is an example of specifying your application’s stack name for the prod environment.

    TOML
    [prod.global.parameters]
    stack_name = "prod-app"
    YAML
    prod: global: parameters: stack_name: prod-app
  3. Use the --config-env option to specify the environment to use.

    The following is an example:

    $ sam deploy --config-env "prod"
To configure parameter values
  1. Specify the AWS SAM CLI command that you’d like to configure parameter values for. To configure parameter values for all AWS SAM CLI commands, use the global identifier.

    The following is an example of specifying parameter values for the default environment’s sam deploy command:

    TOML
    [default.deploy.parameters]
    confirm_changeset = true
    YAML
    default: deploy: parameters: confirm_changeset: true

    The following is an example of specifying parameter values for all AWS SAM CLI commands in the default environment:

    TOML
    [default.global.parameters]
    stack_name = "sam-app"
    YAML
    default: global: parameters: stack_name: sam-app
  2. You can also specify parameter values and modify your configuration file through the AWS SAM CLI interactive flow.

    The following is an example of the sam deploy --guided interactive flow:

    $ sam deploy --guided Configuring SAM deploy ====================== Looking for config file [samconfig.toml] : Found Reading default arguments : Success Setting default arguments for 'sam deploy' ========================================= Stack Name [sam-app]: ENTER AWS Region [us-west-2]: ENTER #Shows you resources changes to be deployed and require a 'Y' to initiate deploy Confirm changes before deploy [Y/n]: n #SAM needs permission to be able to create roles to connect to the resources in your template Allow SAM CLI IAM role creation [Y/n]: ENTER #Preserves the state of previously provisioned resources when an operation fails Disable rollback [y/N]: ENTER HelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y Save arguments to configuration file [Y/n]: ENTER SAM configuration file [samconfig.toml]: ENTER SAM configuration environment [default]: ENTER

For more information, see Creating and modifying configuration files.

Examples

Basic TOML example

The following is an example of a samconfig.toml configuration file:

...
version = 0.1

[default]
[default.global]
[default.global.parameters]
stack_name = "sam-app"

[default.build.parameters]
cached = true
parallel = true

[default.deploy.parameters]
capabilities = "CAPABILITY_IAM"
confirm_changeset = true
resolve_s3 = true

[default.sync.parameters]
watch = true

[default.local_start_api.parameters]
warm_containers = "EAGER"

[prod]
[prod.sync]
[prod.sync.parameters]
watch = false

Basic YAML example

The following is an example of a samconfig.yaml configuration file:

version 0.1 default: global: parameters: stack_name: sam-app build: parameters: cached: true parallel: true deploy: parameters: capabilities: CAPABILITY_IAM confirm_changeset: true resolve_s3: true sync: parameters: watch: true local_start_api: parameters: warm_containers: EAGER prod: sync: parameters: watch: false