AWS SAM CLI configuration file - AWS Serverless Application Model

AWS SAM CLI configuration file

The AWS SAM CLI supports a project-level configuration file that stores default parameters for its commands. This configuration file is in the TOML file format. The default file name is samconfig.toml, and the file's default location is your project's root directory, which is the directory that contains your project's AWS SAM template file.

You can manually edit this file to set default parameters for any AWS SAM CLI command.

In addition, the sam deploy --guided command writes a subset of parameters to your configuration file. For more details about this functionality, see Writing configurations with sam deploy --guided later in this topic.


Here is an example configuration file that contains seven parameters for the default environment and the deploy command:

 stack_name = "my-app-stack"
 s3_bucket = "my-source-bucket"
 s3_prefix = "my-s3-prefix"
 region = "us-west-2"
 confirm_changeset = true
 capabilities = "CAPABILITY_IAM"
 tags = "project=\"my-application\" stage=\"production\""

Configuration file rules

The AWS SAM CLI applies the following rules to configuration files:

File name and location

  • The default configuration file is named samconfig.toml and is located in your project's root directory.

  • You can override the default file name and location using the --config-file parameter.


  • The AWS SAM CLI uses TOML tables to group configuration entries by environment and command.

  • The format of the table header is [environment.command.parameters]. For example, for the sam deploy command, the configuration table header is [default.deploy.parameters].

  • For subcommands, the format of the table header is [environment.command_subcommand.parameters]. That is, delimit the command and subcommand with _ (underscore). For example, for the sam local invoke command, the configuration table header is [default.local_invoke.parameters].

  • If any command or subcommand contains a - (hyphen) character, replace it with with _ (underscore). For example, for the sam local start-api command, the configuration table header is [default.local_start_api.parameters].

  • The default environment name is default. You can override the default environment name using the --config-env parameter.

  • A single configuration file can contain tables for multiple environments and multiple commands/subcommands.

Configuration entries

  • Each configuration entry is a TOML key-value pair.

  • The configuration key is the long-form parameter name with the - (hyphen) character replaced with _ (underscore). For the list of available parameters for each command, see the AWS SAM CLI command reference, or run sam command --help.

  • The configuration value can take the following forms:

    • For parameters that take an argument, the entry value is the argument surrounded by double quotes. For example, region = "us-west-2".

      • For multiple arguments, the arguments are space-delimited within double quotes. For example, capabilities = "CAPABILITY_IAM CAPABILITY_NAMED_IAM".

      • For arguments that are key-value pairs, the pairs are space-delimited and value of each pair is surrounded by encoded double quotes. For example, tags = "project=\"my-application\" stage=\"production\"".

    • For toggle parameters, the value can be true or false (no quotes). For example, confirm_changeset = true.


  • Parameter values that you provide on the command line take precedence over corresponding entries in the configuration file. For example, if your configuration file contains the entry stack_name = "DefaultStack" and you run the command sam deploy --stack-name MyCustomStack, then the deployed stack name is MyCustomStack.

  • For the parameter_overrides entry, both the parameter values that you provide on the command line and entries in the configuration file take precedence over corresponding objects declared in the Parameters section of the template file.

Writing configurations with sam deploy --guided

When you run the sam deploy --guided command, the AWS SAM CLI guides you through the deployment with a series of prompts.

These prompts include the question "Save arguments to samconfig.toml [Y/n]:". If you respond Y to this prompt, the AWS SAM CLI updates the configuration file with values for the following parameters:

  • stack_name

  • s3_bucket

  • s3_prefix

  • image_repository

  • region

  • confirm_changeset

  • capabilities

  • signing_profiles

  • parameter_overrides

If you've previously written a configuration file, the AWS SAM CLI reads it and uses those parameter values as the default values for the corresponding prompts. If you specify values on the command line for any of these parameters, the AWS SAM CLI uses those values as the default values.

To set any parameter other than those previously listed, you must manually edit the configuration file.