# AWS SAM CLI AWS Serverless Application Model Command Line Interface (AWS SAM CLI) is a command-line tool for local development and testing of serverless applications. The AWS SAM CLI allows you to build, transform, deploy, debug, package, initialize, and sync your serverless applications locally before deploying to the cloud. AWS SAM CLI works with serverless applications that are defined using different frameworks and infrastructure as code (IaC) tools, with varying levels of support: + **AWS SAM templates** – Provides native support with the full feature set, including local testing, debugging, packaging, and deployment capabilities. + **AWS CDK applications** – Supports local testing of Lambda functions after you synthesize the AWS CDK application to CloudFormation templates using the cdk synth command. + **CloudFormation templates** – Offers direct compatibility because AWS SAM extends CloudFormation, supporting serverless resources that are defined in standard CloudFormation templates. + **Terraform applications** – Provides limited support for building and local testing of Lambda functions. Requires you to generate AWS SAM template artifacts that represent your Terraform-defined Lambda functions. For the most comprehensive feature support and streamlined developer experience, we recommend using native AWS SAM templates. **Topics** + [How AWS SAM CLI commands are documented](#using-sam-cli-documentation) + [Configuring the AWS SAM CLI](using-sam-cli-configure.md) + [AWS SAM CLI core commands](using-sam-cli-corecommands.md) + [Local testing with AWS SAM CLI](using-sam-cli-local-testing.md) ## How AWS SAM CLI commands are documented AWS SAM CLI commands are documented using the following format: + **Prompt** – The Linux prompt is documented by default and is displayed as (`$ `). For commands that are Windows specific, (`> `) is used as the prompt. Do not include the prompt when you type commands. + **Directory** – When commands must be executed from a specific directory, the directory name is shown before the prompt symbol. + **User input** – Command text that you enter at the command line is formatted as **user input**. + **Replaceable text** – Variable text, such as file names and parameters are formatted as *replaceable text*. In multiple-line commands or commands where specific keyboard input is required, keyboard input can also be shown as replaceable text. For example, *ENTER*. + **Output** – Output returned as a response to the command is formatted as `computer output`. The following `sam deploy` command and output is an example: ``` $ sam deploy --guided --template template.yaml 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]: ENTER #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 ``` 1. `sam deploy --guided --template template.yaml` is the command you enter at the command line. 1. **sam deploy --guided --template** should be provided as is. 1. *template.yaml* can be replaced with your specific file name. 1. The output starts at `Configuring SAM deploy`. 1. In the output, *ENTER* and *y* indicate replaceable values that you provide. # Configuring the AWS SAM CLI One of the benefits of AWS SAM is that it optimizes a developer's time by removing repetitive tasks. AWS SAM CLI includes a configuration file named `samconfig` for this purpose. By default, no configuration to the AWS SAM CLI is needed, but you can update your configuration file to allow you to run commands with fewer parameters by allowing AWS SAM to instead reference your customized parameters in your configuration file. The examples in the following table show how you can optimize your commands: | Original | Optimized with `samconfig` | | --- | --- | | **sam build --cached --parallel --use-containers** | **sam build** | | **sam local invoke --env-vars locals.json** | **sam local invoke** | | **sam local start-api --env-vars locals.json --warm-containers EAGER** | **sam local start-api** | The AWS SAM CLI provides a set of commands to help developers create, develop, and deploy serverless applications. Each of these commands is configurable with optional flags based on the preferences of the application and developer. For more information, see the [AWS SAM CLI content in GitHub](https://github.com/aws/aws-sam-cli) The topics in this section show you how to create your [AWS SAM CLI configuration file](serverless-sam-cli-config.md) and customize its default settings to optimize development time for your serverless application. **Topics** + [How to create your configuration file (the `samconfig` file)](#using-sam-cli-configure-create) + [Configure project settings](#using-sam-cli-configure-project) + [Configure credentials and basic settings](#using-sam-cli-configure-basic) ## How to create your configuration file (the `samconfig` file) The AWS SAM CLI configuration file (filename `samconfig`) is a text file that typically uses the TOML structure, but can also be in YAML. When using an AWS Quick Start Template, this file is created when you run the **sam init** command. You can update this file when you deploy an application using the **sam deploy -\$1-guided** command. After the deployment is complete, the `samconfig` file contains a profile named `default` if you used the default values. When you rerun the **deploy** command, AWS SAM applies the stored configuration settings from this profile. The benefit of the `samconfig` file is that AWS SAM stores configuration settings for any other commands available in addition to the deploy command. Beyond these values created at a new deploy, there are a number of attributes that you can set in the `samconfig` file that can simplify other aspects of the developer workflow with AWS SAM CLI. ## 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](serverless-sam-cli-config.md). ### Using configuration files Configuration files are structured by environment, command, and parameter value. For more information, see [Configuration file basics](serverless-sam-cli-config.md#serverless-sam-cli-config-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: ``` ------ 1. 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 ``` ------ 1. 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 ``` ------ 1. 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](serverless-sam-cli-config.md#serverless-sam-cli-config-using). ### 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 ``` ## 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*: + [Configuration basics](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) + [Configuration and credential file settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) + [Named profiles for the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) + [Using an IAM Identity Center enabled named profile](https://docs.aws.amazon.com/cli/latest/userguide/sso-using-profile.html) For quick setup instructions, see [Step 5: Use the AWS CLI to configure AWS credentials](prerequisites.md#prerequisites-configure-credentials). # AWS SAM CLI core commands AWS SAM CLI has some basic commands you use to create, build, test, deploy, and sync your serverless application. The table below lists these commands and provides links with more information for each. For a complete list of AWS SAM CLI commands, see [AWS SAM CLI command reference](serverless-sam-cli-command-reference.md). | Command | What it does | Related topics | | --- | --- | --- | | **sam build** | Prepares an application for subsequent steps in the developer workflow, such as local testing or deploying to the AWS Cloud. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-corecommands.html) | | **sam deploy** | Deploys an application to the AWS Cloud using CloudFormation. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-corecommands.html) | | **sam init** | Provides options to initialize and create a new serverless application. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-corecommands.html) | | **sam local** | Provides subcommands to test your serverless applications locally. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-corecommands.html) | | **sam remote invoke** | Provides a way to interact with supported AWS resources in the AWS Cloud. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-corecommands.html) | | **sam remote test-event** | Provides a way to access and manage shareable test events for your AWS Lambda functions. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-corecommands.html) | | **sam sync** | Provides options to quickly sync local application changes to the AWS Cloud. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-corecommands.html) | # Local testing with AWS SAM CLI The AWS SAM CLI enables you to test serverless applications locally across different infrastructure as code (IaC) tools. This guide explains how to use the AWS SAM CLI for local testing with various IaC frameworks. Key benefits of using AWS SAM CLI for local testing include: + **Rapid development** - Test code changes without deploying to AWS + **Cost efficiency** - Develop and test without incurring AWS charges + **Offline capability** - Work on your applications without an internet connection + **Simplified debugging** - Step through Lambda function code locally using a debugger + **Realistic testing** - Test your applications using local emulation of AWS services ## Test AWS SAM applications locally For information about testing applications defined using AWS SAM templates, see [Testing and debugging serverless applications](serverless-test-and-debug.md) in this guide. ## Test CloudFormation templates locally To use the AWS SAM CLI's local testing capabilities with CloudFormation, add the AWS SAM transform to your CloudFormation template. For more information, see [AWS SAM template anatomy](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification-template-anatomy.html) for: + Adding AWS SAM transform to CloudFormation templates + Understanding template compatibility + Exploring serverless resource syntax ## Test AWS CDK applications locally You can use the AWS SAM CLI to test AWS CDK applications locally after you synthesize the AWS CDK application to CloudFormation templates using the cdk synth command. For more information, look at [Locally test and build AWS CDK applications with the AWS SAM CLI](https://docs.aws.amazon.com/cdk/v2/guide/testing-locally.html) in the AWS CDK developer guide. This includes: + [Getting started with locally testing](https://docs.aws.amazon.com/cdk/v2/guide/testing-locally.html#testing-locally-getting-started) + [Local testing AWS CDK applications with AWS SAM](https://docs.aws.amazon.com/cdk/v2/guide/testing-locally.html#testing-locally-sam) ## Test Terraform applications locally The AWS SAM CLI supports Terraform projects and Terraform Cloud. You can use it to perform local debugging and testing of: Lambda functions and layers and the Amazon API Gateway HTTP and REST APIs. To set up your environment and learn about all available features, see [Terraform Support](terraform-support.md) in this guide. This includes: + [Getting started with Terraform support for AWS SAM CLI](gs-terraform-support.md) + [Using the AWS SAM CLI with Terraform for local debugging and testing](using-samcli-terraform.md)