# AWS SAM reference
<a name="serverless-sam-reference"></a>

 This section contains AWS SAM reference material. This includes AWS SAM CLI reference material, like reference information on AWS SAM CLI commands and additional AWS SAM CLI information, like configuration, version control, and troubleshooting information. Additionally, this section includes reference information on the AWS SAM specification and the AWS SAM template, like reference information on connectors, image repositories, and deployments. 

## AWS SAM specification and the AWS SAM template
<a name="serverless-sam-spec"></a>

The AWS SAM specification is an open-source specification under the Apache 2.0 license. The current version of the AWS SAM specification is available in the [AWS SAM template](sam-specification.md). AWS SAM specification comes with a simplified short-hand syntax you use to define the functions, events, APIs, configurations, and permissions of your serverless application. 

You interact with AWS SAM specification through the AWS SAM application project directory, which are the folders and files that are created when you run the **sam init** command. This directory includes the AWS SAM template, an important file that defines your AWS resources. The AWS SAM template is an extension of a AWS CloudFormation template. For the full reference for CloudFormation templates, see [Template reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-reference.html) in the *AWS CloudFormation User Guide*.

## AWS SAM CLI command reference
<a name="serverless-sam-cli"></a>

The AWS Serverless Application Model Command Line Interface (AWS SAM CLI) is a command line tool that you can use with AWS SAM templates and supported third-party integrations to build and run your serverless applications.

You can use the AWS SAM CLI commands to develop, test, and deploy your serverless applications to the AWS Cloud. The following are some examples of AWS SAM CLI commands:
+ `sam init` – If you're a first-time AWS SAM CLI user, you can run the `sam init` command without any parameters to create a Hello World application. The command generates a preconfigured AWS SAM template and example application code in the language that you choose.
+ `sam local invoke` and `sam local start-api` – Use these commands to test your application code locally, before deploying it to the AWS Cloud.
+ `sam logs` – Use this command to fetch logs that your Lambda function generates. This can help you with testing and debugging your application after you've deployed it to the AWS Cloud.
+ `sam package` – Use this command to bundle your application code and dependencies into a *deployment package*. You need the deployment package to upload your application to the AWS Cloud.
+ `sam deploy` – Use this command to deploy your serverless application to the AWS Cloud. It creates the AWS resources and sets permissions and other configurations that are defined in the AWS SAM template.

For instructions about installing the AWS SAM CLI, see [Install the AWS SAM CLI](install-sam-cli.md).

## AWS SAM policy templates
<a name="serverless-policy-temps"></a>

With AWS SAM, you can choose from a list of policy templates to scope your AWS Lambda function's permissions to the resources that your application uses. For a list of available policy templates, refer to [Policy template table](serverless-policy-templates.md#serverless-policy-template-table). For general information on policy templates and AWS SAM, refer to [AWS SAM policy templates](serverless-policy-templates.md).

## Topics
<a name="reference-sam-topics"></a>
+ [AWS SAM template](sam-specification.md)
+ [AWS SAM CLI command reference](serverless-sam-cli-command-reference.md)
+ [AWS SAM CLI configuration file](serverless-sam-cli-config.md)
+  [AWS SAM connector reference](reference-sam-connector.md) 
+ [AWS SAM policy templates](serverless-policy-templates.md)
+ [Image repositories for AWS SAM](serverless-image-repositories.md)
+ [Telemetry in the AWS SAM CLI](serverless-sam-telemetry.md)
+ [Set up and manage resource access in your AWS SAM template](sam-permissions.md)

# AWS SAM CLI command reference
<a name="serverless-sam-cli-command-reference"></a>

This section includes reference information on AWS SAM CLI commands. This includes details on usage, a comprehensive list of the different options available for each command, and additional information. When applicable, additional information includes details like arguments, environment variables, and events. See each command for details. For instructions about installing the AWS SAM CLI, see [Install the AWS SAM CLI](install-sam-cli.md).

**Topics**
+ [

# sam build
](sam-cli-command-reference-sam-build.md)
+ [

# sam delete
](sam-cli-command-reference-sam-delete.md)
+ [

# sam deploy
](sam-cli-command-reference-sam-deploy.md)
+ [

# sam init
](sam-cli-command-reference-sam-init.md)
+ [

# sam list
](sam-cli-command-reference-sam-list.md)
+ [

# sam local callback
](sam-cli-command-reference-sam-local-callback.md)
+ [

# sam local execution
](sam-cli-command-reference-sam-local-execution.md)
+ [

# sam local generate-event
](sam-cli-command-reference-sam-local-generate-event.md)
+ [

# sam local invoke
](sam-cli-command-reference-sam-local-invoke.md)
+ [

# sam local start-api
](sam-cli-command-reference-sam-local-start-api.md)
+ [

# sam local start-lambda
](sam-cli-command-reference-sam-local-start-lambda.md)
+ [

# sam logs
](sam-cli-command-reference-sam-logs.md)
+ [

# sam package
](sam-cli-command-reference-sam-package.md)
+ [

# sam pipeline bootstrap
](sam-cli-command-reference-sam-pipeline-bootstrap.md)
+ [

# sam pipeline init
](sam-cli-command-reference-sam-pipeline-init.md)
+ [

# sam publish
](sam-cli-command-reference-sam-publish.md)
+ [

# sam remote callback
](sam-cli-command-reference-sam-remote-callback.md)
+ [

# sam remote execution
](sam-cli-command-reference-sam-remote-execution.md)
+ [

# sam remote invoke
](sam-cli-command-reference-remote-invoke.md)
+ [

# sam remote test-event
](sam-cli-command-reference-remote-test-event.md)
+ [

# sam sync
](sam-cli-command-reference-sam-sync.md)
+ [

# sam traces
](sam-cli-command-reference-sam-traces.md)
+ [

# sam validate
](sam-cli-command-reference-sam-validate.md)

# sam build
<a name="sam-cli-command-reference-sam-build"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam build` command.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam build` command, see [Introduction to building with AWS SAM](using-sam-cli-build.md).

The `sam build` command prepares an application for subsequent steps in the developer workflow, such as local testing or deploying to the AWS Cloud.

## Usage
<a name="ref-sam-cli-build-usage"></a>

```
$ sam build <arguments> <options>
```

## Arguments
<a name="ref-sam-cli-build-args"></a>

**Resource ID**  <a name="ref-sam-cli-build-args-resource-id"></a>
Optional. Instructs AWS SAM to build a single resource declared in an [AWS SAM template](what-is-sam-overview.md#what-is-sam-template). The build artifacts for the specified resource will be the only ones available for subsequent commands in the workflow, i.e. `sam package` and `sam deploy`.

## Options
<a name="ref-sam-cli-build-options"></a>

`--base-dir, -s DIRECTORY`  <a name="ref-sam-cli-build-options-base-dir"></a>
Resolves relative paths to the function's or layer's source code with respect to this directory. Use this option if you want to change how relative paths to source code folders are resolved. By default, relative paths are resolved with respect to the AWS SAM template's location.  
In addition to the resources in the root application or stack you are building, this option also applies nested applications or stacks.  
This option applies to the following resource types and properties:  
+ Resource type: `AWS::Serverless::Function` Property: `CodeUri`
+ Resource type: `AWS::Serverless::Function` Resource attribute: `Metadata` Entry: `DockerContext`
+ Resource type: `AWS::Serverless::LayerVersion` Property: `ContentUri`
+ Resource type: `AWS::Lambda::Function` Property: `Code`
+ Resource type: `AWS::Lambda::LayerVersion` Property: `Content`

`--beta-features | --no-beta-features`  <a name="ref-sam-cli-build-options-beta-features"></a>
Allow or deny beta features.

`--build-dir, -b DIRECTORY`  <a name="ref-sam-cli-build-options-build-dir"></a>
The path to a directory where the built artifacts are stored. This directory and all of its content are removed with this option.

`--build-image TEXT`  <a name="ref-sam-cli-build-options-build-image"></a>
The URI of the container image that you want to pull for the build. By default, AWS SAM pulls the container image from Amazon ECR Public. Use this option to pull the image from another location.  
You can specify this option multiple times. Each instance of this option can take either a string or a key-value pair. If you specify a string, it is the URI of the container image to use for all resources in your application. For example, `sam build --use-container --build-image amazon/aws-sam-cli-build-image-python3.8`. If you specify a key-value pair, the key is the resource name, and the value is the URI of the container image to use for that resource. For example `sam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.8`. With key-value pairs, you can specify different container images for different resources.  
This option only applies if the `--use-container` option is specified, otherwise an error will result.

`--build-in-source | --no-build-in-source`  <a name="ref-sam-cli-build-options-build-in-source"></a>
Provide `--build-in-source` to build your project directly in the source folder.  
The `--build-in-source` option supports the following runtimes and build methods:  
+ **Runtimes** – Any Node.js runtime supported by the `sam init --runtime` option.
+ **Build methods** – `Makefile`, `esbuild`.
The `--build-in-source` option is not compatible with the following options:  
+ `--hook-name`
+ `--use-container `
*Default*: `--no-build-in-source`

`--cached | --no-cached`  <a name="ref-sam-cli-build-options-cached"></a>
Enable or disable cached builds. Use this option to reuse build artifacts that haven't changed from previous builds. AWS SAM evaluates whether you've changed any files in your project directory. By default, builds are not cached. If the `--no-cached` option is invoked, it overrides the `cached = true` setting in samconfig.toml.  
AWS SAM doesn't evaluate whether you've changed third-party modules that your project depends on, where you haven't provided a specific version. For example, if your Python function includes a `requirements.txt` file with the entry `requests=1.x`, and the latest request module version changes from `1.1` to `1.2`, then AWS SAM doesn't pull the latest version until you run a non-cached build.

`--cache-dir`  <a name="ref-sam-cli-build-options-cached-dir"></a>
The directory where the cache artifacts are stored when `--cached` is specified. The default cache directory is `.aws-sam/cache`.

`--config-env TEXT`  <a name="ref-sam-cli-build-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="ref-sam-cli-build-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "`samconfig.toml`" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--container-env-var, -e TEXT`  <a name="ref-sam-cli-build-options-container-env-var"></a>
Environment variables to pass to the build container. You can specify this option multiple times. Each instance of this option takes a key-value pair, where the key is the resource and environment variable, and the value is the environment variable's value. For example: `--container-env-var Function1.GITHUB_TOKEN=TOKEN1 --container-env-var Function2.GITHUB_TOKEN=TOKEN2`.  
This option only applies if the `--use-container` option is specified, otherwise an error will result.

`--container-env-var-file, -ef PATH`  <a name="ref-sam-cli-build-options-container-env-var-file"></a>
The path and file name of a JSON file that contains values for the container's environment variables. For more information about container environment variable files, see [Container environment variable file](serverless-sam-cli-using-build.md#serverless-sam-cli-using-container-environment-file).  
This option only applies if the `--use-container` option is specified, otherwise an error will result.

`--debug`  <a name="ref-sam-cli-build-options-debug"></a>
Turns on debug logging to print debug messages that the AWS SAM CLI generates, and to display timestamps.

`--docker-network TEXT`  <a name="ref-sam-cli-build-options-docker-network"></a>
Specifies the name or ID of an existing Docker network that Lambda Docker containers should connect to, along with the default bridge network. If not specified, the Lambda containers connect only to the default bridge Docker network.

`--exclude, -x`  <a name="ref-sam-cli-build-options-exclude"></a>
The Name of the resource(s) to exclude from the `sam build`. For example, if your template contains `Function1`, `Function2`, and `Function3` and you run `sam build --exclude Function2`, only `Function1` and `Function3` will be built.

`--help`  <a name="ref-sam-cli-build-options-help"></a>
Shows this message and exits.

`--hook-name TEXT`  <a name="ref-sam-cli-build-options-hook-name"></a>
The name of the hook that is used to extend AWS SAM CLI functionality.  
Accepted values: `terraform`.

`--manifest , -m PATH`  <a name="ref-sam-cli-build-options-manifest"></a>
The path to a custom dependency manifest file (for example, package.json) to use instead of the default.

`--mount-symlinks`  <a name="ref-sam-cli-build-options-mount-symlinks"></a>
Ensures the AWS SAM CLI always mounts symlinks that are present in the files to build or invoke. This applies only to symlinks on the top level directory (that is, symlinks that are directly on the function's root). By default, symlinks are not mounted except for those needed to use `build-in-source` for `node_modules` in NodeJS.

`--no-use-container`  <a name="ref-sam-cli-build-options-no-use-container"></a>
An option that allows you to use the IDE toolkit to set default behavior. You can also use `sam build --no-use-container` to run a build in your local machine instead of a docker container.

`--parallel`  <a name="ref-sam-cli-build-options-parallel"></a>
Enables parallel builds. Use this option to build your AWS SAM template's functions and layers in parallel. By default, the functions and layers are built in sequence.

`--parameter-overrides`  <a name="ref-sam-cli-build-options-parameter-overrides"></a>
(Optional) A string that contains CloudFormation parameter overrides encoded as key-value pairs. Uses the same format as the AWS Command Line Interface (AWS CLI). For example: '`ParameterKey`=`KeyPairName`, `ParameterValue`=`MyKey` `ParameterKey`=`InstanceType`, `ParameterValue`=`t1.micro`'. This option is not compatible with `--hook-name`.

`--profile TEXT`  <a name="ref-sam-cli-build-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="ref-sam-cli-build-options-region"></a>
The AWS Region to deploy to. For example, us-east-1.

`--save-params`  <a name="ref-sam-cli-build-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--skip-prepare-infra`  <a name="ref-sam-cli-build-options-skip-prepare-infra"></a>
Skips the preparation stage if no infrastructure changes have been made. Use with the `--hook-name` option.

`--skip-pull-image`  <a name="ref-sam-cli-build-options-skip-pull-image"></a>
Specifies whether the command should skip pulling down the latest Docker image for the Lambda runtime.

`--template-file, --template, -t PATH`  <a name="ref-sam-cli-build-options-template-file"></a>
The path and file name of AWS SAM template file `[default: template.[yaml|yml]]`. This option is not compatible with `--hook-name`.

`--terraform-project-root-path`  <a name="ref-sam-cli-build-options-terraform-project-root-path"></a>
The relative or absolute path to the top-level directory containing your Terraform configuration files or function source code. If these files are located outside of the directory containing your Terraform root module, use this option to specify its absolute or relative path. This option requires that `--hook-name` be set to `terraform`.

`--use-container`, `-u`  <a name="ref-sam-cli-build-options-use-container"></a>
If your functions depend on packages that have natively compiled dependencies, use this option to build your function inside a Lambda-like Docker container.

## Example
<a name="sam-cli-command-reference-sam-build-examples"></a>

For a detailed example and in-depth walkthrough on using the `sam build` subcommand, refer to [Introduction to building with AWS SAM](using-sam-cli-build.md).

# sam delete
<a name="sam-cli-command-reference-sam-delete"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam delete` command.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam delete` command deletes an AWS SAM application by deleting the CloudFormation stack, the artifacts that were packaged and deployed to Amazon S3 and Amazon ECR, and the AWS SAM template file.

This command also checks whether there is an Amazon ECR companion stack deployed, and if so prompts the user about deleting that stack and Amazon ECR repositories. If `--no-prompts` is specified, then companion stacks and Amazon ECR repositories are deleted by default.

## Usage
<a name="sam-cli-command-reference-sam-delete-usage"></a>

```
$ sam delete <options>
```

## Options
<a name="sam-cli-command-reference-sam-delete-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-delete-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is `default`. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-sam-delete-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is `samconfig.toml` in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--debug`  <a name="sam-cli-command-reference-sam-delete-options-debug"></a>
Turns on debug logging to print the debug message that the AWS SAM CLI generates and to display timestamps.

`--help`  <a name="sam-cli-command-reference-sam-delete-options-help"></a>
Shows this message and exits.

`--no-prompts`  <a name="sam-cli-command-reference-sam-delete-options-no-prompts"></a>
Specify this option to have AWS SAM operate in non-interactive mode. The stack name must be provided, either with the `--stack-name` option, or in the configuration `toml` file.

`--profile TEXT`  <a name="sam-cli-command-reference-sam-delete-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="sam-cli-command-reference-sam-delete-options-region"></a>
The AWS Region to deploy to. For example, us-east-1.

`--s3-bucket`  <a name="sam-cli-command-reference-sam-delete-options-s3-bucket"></a>
The path of the Amazon S3 bucket you want to delete.

`--s3-prefix`  <a name="sam-cli-command-reference-sam-delete-options-s3-prefix"></a>
The prefix of the Amazon S3 bucket you want to delete.

`--save-params`  <a name="sam-cli-command-reference-sam-delete-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--stack-name TEXT`  <a name="sam-cli-command-reference-sam-delete-options-stack-name"></a>
The name of the CloudFormation stack that you want to delete.

## Examples
<a name="sam-cli-command-reference-sam-delete-examples"></a>

The following command deletes the stack `MY-STACK`. 

```
$ sam delete --stack-name MY-STACK
```

The following command deletes the stack `MY-STACK` and the S3 bucket `sam-s3-demo-bucket`:

```
$ sam delete \
    --stack-name MyStack \
    --s3-bucket MySAMBucket
```

# sam deploy
<a name="sam-cli-command-reference-sam-deploy"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam deploy` command.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam deploy` command, see [Introduction to deploying with AWS SAM](using-sam-cli-deploy.md).

The `sam deploy` command deploys an application to the AWS Cloud using AWS CloudFormation.

## Usage
<a name="ref-sam-cli-deploy-usage"></a>

```
$ <environment variables> sam deploy <options>
```

## Environment variables
<a name="ref-sam-cli-deploy-env"></a>

`SAM_CLI_POLL_DELAY`  <a name="ref-sam-cli-deploy-env-sam-cli-poll-delay"></a>
Set the `SAM_CLI_POLL_DELAY` environment variable with a value of seconds in your shell to configure how often the AWS SAM CLI checks the CloudFormation stack state, which is useful when seeing throttling from CloudFormation. This env variable is used for polling `describe_stack` API calls, which are made while running `sam deploy`.   
The following is an example of this variable:  

```
$ SAM_CLI_POLL_DELAY=5 sam deploy
```

## Options
<a name="ref-sam-cli-deploy-options"></a>

`--capabilities LIST`  <a name="ref-sam-cli-deploy-options-capabilities"></a>
A list of capabilities that you must specify to allow CloudFormation to create certain stacks. Some stack templates might include resources that affect permissions in your AWS account, for example, by creating new AWS Identity and Access Management (IAM) users. For those stacks, you must explicitly acknowledge their capabilities by specifying this option. The only valid values are `CAPABILITY_IAM` and `CAPABILITY_NAMED_IAM`. If you have IAM resources, then you can specify either capability. If you have IAM resources with custom names, then you must specify `CAPABILITY_NAMED_IAM`. If you don't specify this option, then the operation returns an `InsufficientCapabilities` error.  
When you deploy an application that contains nested applications, you must use `CAPABILITY_AUTO_EXPAND` to acknowledge the application contains nested applications. For more information, see [Deploying nested applications](serverless-sam-template-nested-applications.md#serverless-sam-templates-nested-applications-deploying).

`--config-env TEXT`  <a name="ref-sam-cli-deploy-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is `default`. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="ref-sam-cli-deploy-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is `samconfig.toml` in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--confirm-changeset | --no-confirm-changeset`  <a name="ref-sam-cli-deploy-options-confirm-changeset"></a>
Prompt to confirm whether the AWS SAM CLI deploys the computed changeset.

`--debug`  <a name="ref-sam-cli-deploy-options-debug"></a>
Turn on debug logging to print the debug message that the AWS SAM CLI generates and to display timestamps.

`--disable-rollback | --no-disable-rollback`  <a name="ref-sam-cli-deploy-options-disable-rollback"></a>
Specify whether to roll back your CloudFormation stack if an error occurs during a deployment. By default, if there's an error during a deployment, your CloudFormation stack rolls back to the last stable state. If you specify `--disable-rollback` and an error occurs during a deployment, then resources that were created or updated before the error occurred aren't rolled back.

`--fail-on-empty-changeset | --no-fail-on-empty-changeset`  <a name="ref-sam-cli-deploy-options-fail-on-empty-changeset"></a>
Specify whether to return a non-zero exit code if there are no changes to make to the stack. The default behavior is to return a non-zero exit code.

`--force-upload`  <a name="ref-sam-cli-deploy-options-force-upload"></a>
Specify this option to upload artifacts even if they match existing artifacts in the Amazon S3 bucket. Matching artifacts are overwritten.

`--guided, -g`  <a name="ref-sam-cli-deploy-options-guided"></a>
Specify this option to have the AWS SAM CLI use prompts to guide you through the deployment.

`--help`  <a name="ref-sam-cli-deploy-options-help"></a>
Show this message and exit.

`--image-repositories TEXT`  <a name="ref-sam-cli-deploy-options-image-repositories"></a>
A mapping of functions to their Amazon ECR repository URI. Reference functions by their logical ID. The following is an example:  

```
$ sam deploy --image-repositories Function1=123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo
```
You can specify this option multiple times in a single command.

`--image-repository TEXT`  <a name="ref-sam-cli-deploy-options-image-repository"></a>
The name of the Amazon ECR repository where this command uploads your function's image. This option is required for functions declared with the `Image` package type.

`--kms-key-id TEXT`  <a name="ref-sam-cli-deploy-options-kms-key-id"></a>
The ID of an AWS Key Management Service (AWS KMS) key used to encrypt artifacts that are at rest in the Amazon S3 bucket. If you don't specify this option, then AWS SAM uses Amazon S3-managed encryption keys.

`--metadata`  <a name="ref-sam-cli-deploy-options-metadata"></a>
A map of metadata to attach to all artifacts that are referenced in your template.

`--no-execute-changeset`  <a name="ref-sam-cli-deploy-options-no-execute-changeset"></a>
Indicates whether to apply the changeset. Specify this option if you want to view your stack changes before applying the changeset. This command creates an CloudFormation changeset and then exits without applying the changeset. To apply the changeset, run the same command without this option.

`--no-progressbar`  <a name="ref-sam-cli-deploy-options-no-progressbar"></a>
Do not display a progress bar when uploading artifacts to Amazon S3.

`--notification-arns LIST`  <a name="ref-sam-cli-deploy-options-notification-arns"></a>
A list of Amazon Simple Notification Service (Amazon SNS) topic ARNs that CloudFormation associates with the stack.

`--on-failure [ROLLBACK | DELETE | DO_NOTHING]`  <a name="ref-sam-cli-deploy-options-on-failure"></a>
Specify the action to take when a stack fails to create.  
The following options are available:  
+ `ROLLBACK` – Rolls back the stack to a previous known good state.
+ `DELETE` – Rolls back the stack to a previous known good state, if one exists. Otherwise, deletes the stack.
+ `DO_NOTHING` – Neither rolls back nor deletes the stack. The effect is the same as that of `--disable-rollback`.
The default behavior is `ROLLBACK`.  
You can specify either the `--disable-rollback` option or the `--on-failure` option, but not both.

`--parameter-overrides LIST`  <a name="ref-sam-cli-deploy-options-parameter-overrides"></a>
A string that contains CloudFormation parameter overrides encoded as key-value pairs. Each override uses the format `ParameterKey=name,ParameterValue=value`. Multiple overrides are separated by spaces. Here are two examples:  

```
$ sam deploy --parameter-overrides ParameterKey=value1,ParameterValue=value2
```

```
$ sam deploy --parameter-overrides ParameterKey=value1,ParameterValue=value2 ParameterKey=hello,ParameterValue=world ParameterKey=apple,ParameterValue=banana
```

`--profile TEXT`  <a name="ref-sam-cli-deploy-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="ref-sam-cli-deploy-options-region"></a>
The AWS Region to deploy to. For example, us-east-1.

`--resolve-image-repos`  <a name="ref-sam-cli-deploy-options-resolve-image-repos"></a>
Automatically create Amazon ECR repositories to use for packaging and deploying for non-guided deployments. This option applies only to functions and layers with `PackageType: Image` specified. If you specify the `--guided` option, then the AWS SAM CLI ignores `--resolve-image-repos`.  
If AWS SAM automatically creates any Amazon ECR repositories for functions or layers with this option, and you later delete those functions or layers from your AWS SAM template, then the corresponding Amazon ECR repositories are automatically deleted.

`--resolve-s3`  <a name="ref-sam-cli-deploy-options-resolve-s3"></a>
Automatically create an Amazon S3 bucket to use for packaging and deploying for non-guided deployments. If you specify the `--guided` option, then the AWS SAM CLI ignores `--resolve-s3`. If you specify both the `--s3-bucket` and `--resolve-s3` options, then an error occurs.

`--role-arn TEXT`  <a name="ref-sam-cli-deploy-options-role-arn"></a>
The Amazon Resource Name (ARN) of an IAM role that CloudFormation assumes when applying the changeset.

`--s3-bucket TEXT`  <a name="ref-sam-cli-deploy-options-s3-bucket"></a>
The name of the Amazon S3 bucket where this command uploads your CloudFormation template. If your template is larger than 51,200 bytes, then either the `--s3-bucket` option or the `--resolve-s3` option is required. If you specify both the `--s3-bucket` and `--resolve-s3` options, then an error occurs.

`--s3-prefix TEXT`  <a name="ref-sam-cli-deploy-options-s3-prefix"></a>
The prefix added to the names of the artifacts that are uploaded to the Amazon S3 bucket. The prefix name is a path name (folder name) for the Amazon S3 bucket.

`--save-params`  <a name="ref-sam-cli-deploy-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--signing-profiles LIST`  <a name="ref-sam-cli-deploy-options-signing-profiles"></a>
The list of signing profiles to sign your deployment packages with. This option takes a list of key-value pairs, where the key is the name of the function or layer to sign, and the value is the signing profile, with an optional profile owner delimited with `:`. For example, `FunctionNameToSign=SigningProfileName1 LayerNameToSign=SigningProfileName2:SigningProfileOwner`.

`--stack-name TEXT`  <a name="ref-sam-cli-deploy-options-stack-name"></a>
(Required) The name of the CloudFormation stack that you're deploying to. If you specify an existing stack, then the command updates the stack. If you specify a new stack, then the command creates it.

`--tags LIST`  <a name="ref-sam-cli-deploy-options-tags"></a>
A list of tags to associate with the stack that is created or updated. CloudFormation also propagates these tags to resources in the stack that support it.

`--template-file, --template, -t PATH`  <a name="ref-sam-cli-deploy-options-template-file"></a>
The path and file name where your AWS SAM template is located.  
If you specify this option, then AWS SAM deploys only the template and the local resources that it points to.

`--use-json`  <a name="ref-sam-cli-deploy-options-use-json"></a>
Output JSON for the CloudFormation template. The default output is YAML.

## Example
<a name="sam-cli-command-reference-sam-deploy-examples"></a>

For a detailed example and in-depth walkthrough on using the `sam deploy` subcommand, refer to [Introduction to deploying with AWS SAM](using-sam-cli-deploy.md).

# sam init
<a name="sam-cli-command-reference-sam-init"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam init` command.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam init` command, see [Create your application in AWS SAM](using-sam-cli-init.md).

The `sam init` command provides options to initialize a new serverless application.

## Usage
<a name="sam-cli-command-reference-sam-init-usage"></a>

```
$ sam init <options>
```

## Options
<a name="sam-cli-command-reference-sam-init-options"></a>

`--app-template TEXT`  <a name="sam-cli-command-reference-sam-init-options-app-template"></a>
The identifier of the managed application template that you want to use. If you're not sure, call `sam init` without options for an interactive workflow.  
This parameter is required if `--no-interactive` is specified and `--location` is not provided.  
This parameter is available only in AWS SAM CLI version 0.30.0 and later. Specifying this parameter with an earlier version results in an error.

`--application-insights | --no-application-insights`  <a name="sam-cli-command-reference-sam-init-options-application-insights"></a>
 Activate Amazon CloudWatch Application Insights monitoring for your application. To learn more, see [Using CloudWatch Application Insights to monitor your AWS SAM serverless applications](monitor-app-insights.md).   
 The default option is `--no-application-insights`. 

`--architecture, -a [ x86_64 | arm64 ]`  <a name="sam-cli-command-reference-sam-init-options-architecture"></a>
The instruction set architecture for your application's Lambda functions. Specify one of `x86_64` or `arm64`.

`--base-image [ amazon/dotnet8-base | amazon/dotnet6-base | amazon/java25-base | amazon/java21-base | amazon/java17-base | amazon/java11-base | amazon/nodejs24.x-base | amazon/nodejs22.x-base | amazon/nodejs20.x-base | amazon/nodejs18.x-base | amazon/nodejs16.x-base | amazon/python3.14-base | amazon/python3.13-base | amazon/python3.12-base | amazon/python3.11-base | amazon/python3.10-base | amazon/python3.9-base | amazon/python3.8-base | amazon/ruby3.4-base | amazon/ruby3.3-base | amazon/ruby3.2-base ]`  <a name="sam-cli-command-reference-sam-init-options-base-image"></a>
The base image of your application. This option applies only when the package type is `Image`.  
This parameter is required if `--no-interactive` is specified, `--package-type` is specified as `Image`, and `--location` is not specified.

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-init-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-sam-init-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "samconfig.toml" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--debug`  <a name="sam-cli-command-reference-sam-init-options-debug"></a>
Turns on debug logging to print debug messages that the AWS SAM CLI generates, and to display timestamps.

`--dependency-manager, -d [ gradle | mod | maven | bundler | npm | cli-package | pip ]`  <a name="sam-cli-command-reference-sam-init-options-dependency-manager"></a>
The dependency manager of your Lambda runtime.

`--extra-content`  <a name="sam-cli-command-reference-sam-init-options-extra-content"></a>
Override any custom parameters in the template's `cookiecutter.json` configuration, for example, `{"customParam1": "customValue1", "customParam2":"customValue2"}`.

`--help, -h`  <a name="sam-cli-command-reference-sam-init-options-help"></a>
Shows this message and exits.

`--location, -l TEXT`  <a name="sam-cli-command-reference-sam-init-options-location"></a>
The template or application location (Git, Mercurial, HTTP/HTTPS, .zip file, path).  
This parameter is required if `--no-interactive` is specified and `--runtime`, `--name`, and `--app-template` are not provided.  
For Git repositories, you must use the location of the root of the repository.  
For local paths, the template must be in either .zip file or [Cookiecutter](https://cookiecutter.readthedocs.io/en/latest/README.html) format.

`--name, -n TEXT`  <a name="sam-cli-command-reference-sam-init-options-name"></a>
The name of your project to be generated as a directory.  
This parameter is required if `--no-interactive` is specified and `--location` is not provided.

`--no-input`  <a name="sam-cli-command-reference-sam-init-options-no-input"></a>
Disables Cookiecutter prompting and accepts the vcfdefault values that are defined in the template configuration.

`--no-interactive`  <a name="sam-cli-command-reference-sam-init-options-no-interactive"></a>
Disable interactive prompting for init parameters, and fail if any required values are missing.

`--output-dir, -o PATH`  <a name="sam-cli-command-reference-sam-init-options-output-dir"></a>
The location where the initialized application is output.

`--package-type [ Zip | Image ]`  <a name="sam-cli-command-reference-sam-init-options-package-type"></a>
The package type of the example application. `Zip` creates a .zip file archive, and `Image` creates a container image.

`--runtime, -r [ dotnet8 | dotnet6 | java25 | java21 | java17 | java11 | nodejs24.x | nodejs22.x | nodejs20.x | nodejs18.x | nodejs16.x | python3.14 | python3.13 | python3.12 | python3.11 | python3.10 | python3.9 | python3.8 | ruby3.4 | ruby3.3 | ruby3.2 ]`  <a name="sam-cli-command-reference-sam-init-options-runtime"></a>
The Lambda runtime of your application. This option applies only when the package type is `Zip`.  
This parameter is required if `--no-interactive` is specified, `--package-type` is specified as `Zip`, and `--location` is not specified.

`--save-params`  <a name="sam-cli-command-reference-sam-init-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--tracing | --no-tracing`  <a name="sam-cli-command-reference-sam-init-options-tracing"></a>
Activate AWS X-Ray tracing for your Lambda functions.

## Example
<a name="sam-cli-command-reference-sam-init-examples"></a>

For a detailed example and in-depth walkthrough on using the `sam init` subcommand, refer to [Create your application in AWS SAM](using-sam-cli-init.md).

# sam list
<a name="sam-cli-command-reference-sam-list"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam list` command.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam list` command outputs important information about the resources in your serverless application and the state of your serverless application. Use **sam list** before and after deployment to assist during local and cloud development.

## Usage
<a name="sam-cli-command-reference-sam-list-usage"></a>

```
$ sam list <options> <subcommand>
```

## Options
<a name="sam-cli-command-reference-sam-list-options"></a>

`--help, -h`  <a name="sam-cli-command-reference-sam-list-options-help"></a>
Show this message and exit.

## Subcommands
<a name="sam-cli-command-reference-sam-list-subcommands"></a>

`endpoints`  <a name="sam-cli-command-reference-sam-list-subcommands-endpoints"></a>
Displays a list of cloud and local endpoints from your CloudFormation stack. For more information, see [sam list endpoints](sam-cli-command-reference-sam-list-endpoints.md).

`resources`  <a name="sam-cli-command-reference-sam-list-subcommands-resources"></a>
Displays the resources in your AWS Serverless Application Model (AWS SAM) template that are created in AWS CloudFormation at deployment. For more information, see [sam list resources](sam-cli-command-reference-sam-list-resources.md).

`stack-outputs`  <a name="sam-cli-command-reference-sam-list-subcommands-stack-outputs"></a>
Displays the outputs of your CloudFormation stack from an AWS SAM or CloudFormation template. For more information, see [sam list stack-outputs](sam-cli-command-reference-sam-list-stack-outputs.md).

# sam list endpoints
<a name="sam-cli-command-reference-sam-list-endpoints"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam list endpoints` subcommand.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam list endpoints` subcommand displays a list of cloud and local endpoints from your CloudFormation stack. You can interact with these resources through the **sam local** and **sam sync** commands.

AWS Lambda and Amazon API Gateway resource types are supported with this command.

**Note**  
Custom domains are supported when configured for your Amazon API Gateway resources. This command will output the custom domain instead of the default endpoint.

## Usage
<a name="sam-cli-command-reference-sam-list-endpoints-usage"></a>

```
$ sam list endpoints <options>
```

## Options
<a name="sam-cli-command-reference-sam-list-endpoints-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-list-endpoints-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use.  
*Default value*: `default`  
For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file TEXT`  <a name="sam-cli-command-reference-sam-list-endpoints-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use.  
*Default value*: `samconfig.toml` in current working directory.  
For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--debug`  <a name="sam-cli-command-reference-sam-list-endpoints-options-debug"></a>
Turn on debug logging to print debug messages generated by the AWS SAM CLI with timestamps.

`--help, -h`  <a name="sam-cli-command-reference-sam-list-endpoints-options-help"></a>
Show this message and exit.

`--output [json|table]`  <a name="sam-cli-command-reference-sam-list-endpoints-options-output"></a>
Specify the format to output results.  
*Default value*: `table`

`--profile TEXT`  <a name="sam-cli-command-reference-sam-list-endpoints-options-profile"></a>
Select a specific profile from your credential file to get AWS credentials.

`--region TEXT`  <a name="sam-cli-command-reference-sam-list-endpoints-options-region"></a>
Set the AWS region of the service. For example, `us-east-1`.

`--save-params`  <a name="sam-cli-command-reference-sam-list-endpoints-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--stack-name TEXT`  <a name="sam-cli-command-reference-sam-list-endpoints-options-stack-name"></a>
Name of the deployed CloudFormation stack. The stack name can be found in your application's `samconfig.toml` file or designated configuration file.  
When this option is not specified, local resources defined in your template will display.

`--template-file, --template, -t PATH`  <a name="sam-cli-command-reference-sam-list-endpoints-options-template"></a>
AWS SAM template file.  
*Default value*: `template.[yaml|yml|json]`

## Examples
<a name="sam-cli-command-reference-sam-list-endpoints-examples"></a>

Display an output, in json format, of deployed resource endpoints from your CloudFormation stack named `test-stack`.

```
$ sam list endpoints --stack-name test-stack --output json
			
[
  {
    "LogicalResourceId": "HelloWorldFunction",
    "PhysicalResourceId": "sam-app-test-list-HelloWorldFunction-H85Y7yIV7ZLq",
    "CloudEndpoint": "https://zt55oi7kbljxjmcoahsj3cknwu0rposq.lambda-url.us-east-1.on.aws/",
    "Methods": "-"
  },
  {
    "LogicalResourceId": "ServerlessRestApi",
    "PhysicalResourceId": "uj80uoe2o2",
    "CloudEndpoint": [
      "https://uj80uoe2o2.execute-api.us-east-1.amazonaws.com/Prod",
      "https://uj80uoe2o2.execute-api.us-east-1.amazonaws.com/Stage"
    ],
    "Methods": [
      "/hello['get']"
    ]
  }
]
```

# sam list resources
<a name="sam-cli-command-reference-sam-list-resources"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam list resources` subcommand.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam list resources` subcommand displays the resources in your AWS Serverless Application Model (AWS SAM) template that are created in AWS CloudFormation by the AWS SAM transform at deployment.

Use **sam list resources** with an AWS SAM template before deployment to see resources that will be created. Provide an CloudFormation stack name to view a consolidated list that includes deployed resources.

**Note**  
To generate a list of resources from your AWS SAM template, a local transform of your template is performed. Resources that will be deployed with conditions, such as within a specific region, are included in this list.

## Usage
<a name="sam-cli-command-reference-sam-list-resources-usage"></a>

```
$ sam list resources <options>
```

## Options
<a name="sam-cli-command-reference-sam-list-resources-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-list-resources-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use.  
*Default value*: `default`  
For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file TEXT`  <a name="sam-cli-command-reference-sam-list-resources-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use.  
*Default value*: `samconfig.toml` in current working directory.  
For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--debug`  <a name="sam-cli-command-reference-sam-list-resources-options-debug"></a>
Turn on debug logging to print debug messages generated by the AWS SAM CLI with timestamps.

`--help, -h`  <a name="sam-cli-command-reference-sam-list-resources-options-help"></a>
Show this message and exit.

`--output [json|table]`  <a name="sam-cli-command-reference-sam-list-resources-options-output"></a>
Specify the format to output results.  
*Default value*: `table`

`--profile TEXT`  <a name="sam-cli-command-reference-sam-list-resources-options-profile"></a>
Select a specific profile from your credential file to get AWS credentials.

`--region TEXT`  <a name="sam-cli-command-reference-sam-list-resources-options-region"></a>
Set the AWS region of the service. For example, `us-east-1`.

`--save-params`  <a name="sam-cli-command-reference-sam-list-resources-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--stack-name TEXT`  <a name="sam-cli-command-reference-sam-list-resources-options-stack-name"></a>
Name of the deployed CloudFormation stack. The stack name can be found in your application's `samconfig.toml` file or designated configuration file.  
When provided, resource logical IDs from your template will be mapped to their corresponding physical IDs in CloudFormation. To learn more about physical IDs, see [ Resource fields](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html#resources-section-structure-resource-fields) in the *AWS CloudFormation User Guide*.  
When this option is not specified, local resources defined in your template will display.

`--template-file, --template, -t PATH`  <a name="sam-cli-command-reference-sam-list-resources-options-"></a>
AWS SAM template file.  
*Default value*: `template.[yaml|yml|json]`

## Examples
<a name="sam-cli-command-reference-sam-list-resources-examples"></a>

Display an output, in table format, of local resources from your AWS SAM template and deployed resources from your CloudFormation stack named `test-stack`. Run from the same directory as your local template.

```
$ sam list resources --stack-name test-stack --output table
			
-------------------------------------------------------------------------------------------------------------------------
Logical ID                                                   Physical ID
-------------------------------------------------------------------------------------------------------------------------
HelloWorldFunction                                           sam-app-test-list-HelloWorldFunction-H85Y7yIV7ZLq
HelloWorldFunctionHelloWorldPermissionProd                   sam-app-test-list-
                                                             HelloWorldFunctionHelloWorldPermissionProd-1QH7CPOCBL2IK
HelloWorldFunctionRole                                       sam-app-test-list-HelloWorldFunctionRole-SRJDMJ6F7F41
ServerlessRestApi                                            uj80uoe2o2
ServerlessRestApiDeployment47fc2d5f9d                        pncw5f
ServerlessRestApiProdStage                                   Prod
ServerlessRestApiDeploymentf5716dc08b                        -
-------------------------------------------------------------------------------------------------------------------------
```

# sam list stack-outputs
<a name="sam-cli-command-reference-sam-list-stack-outputs"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam list stack-outputs` subcommand.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam list stack-outputs` subcommand displays the outputs of your AWS CloudFormation stack from an AWS Serverless Application Model (AWS SAM) or CloudFormation template. For more information on `Outputs`, see [Outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html) in the *AWS CloudFormation User Guide*.

## Usage
<a name="sam-cli-command-reference-sam-list-stack-outputs-usage"></a>

```
$ sam list stack-outputs <options>
```

## Options
<a name="sam-cli-command-reference-sam-list-stack-outputs-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-list-stack-outputs-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use.  
*Default value*: `default`  
For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file TEXT`  <a name="sam-cli-command-reference-sam-list-stack-outputs-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use.  
*Default value*: `samconfig.toml` in current working directory.  
For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--debug`  <a name="sam-cli-command-reference-sam-list-stack-outputs-options-debug"></a>
Turn on debug logging to print debug messages generated by the AWS SAM CLI with timestamps.

`--help, -h`  <a name="sam-cli-command-reference-sam-list-stack-outputs-options-help"></a>
Show this message and exit.

`--output [json|table]`  <a name="sam-cli-command-reference-sam-list-stack-outputs-options-output"></a>
Specify the format to output results.  
*Default value*: `table`

`--profile TEXT`  <a name="sam-cli-command-reference-sam-list-stack-outputs-options-profile"></a>
Select a specific profile from your credential file to get AWS credentials.

`--region TEXT`  <a name="sam-cli-command-reference-sam-list-stack-outputs-options-region"></a>
Set the AWS region of the service. For example, `us-east-1`.

`--save-params`  <a name="sam-cli-command-reference-sam-list-stack-outputs-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--stack-name TEXT`  <a name="sam-cli-command-reference-sam-list-stack-outputs-options-"></a>
Name of the deployed CloudFormation stack. The stack name can be found in your application's `samconfig.toml` file or designated configuration file.  
This option is required.

## Examples
<a name="sam-cli-command-reference-sam-list-stack-outputs-examples"></a>

Displays the outputs, in table format, of resources in your CloudFormation stack named `test-stack`.

```
$ sam list stack-outputs --stack-name test-stack --output table
			
------------------------------------------------------------------------------------------------------------------------
OutputKey                                OutputValue                              Description
------------------------------------------------------------------------------------------------------------------------
HelloWorldFunctionIamRole                arn:aws:iam::account-number:role/sam-      Implicit IAM Role created for Hello
                                         app-test-list-HelloWorldFunctionRole-    World function
                                         SRJDMJ6F7F41
HelloWorldApi                            https://uj80uoe2o2.execute-api.us-       API Gateway endpoint URL for Prod
                                         east-1.amazonaws.com/Prod/hello/         stage for Hello World function
HelloWorldFunction                       arn:aws:lambda:us-                       Hello World Lambda Function ARN
                                         east-1:account-number:function:sam-app-
                                         test-list-
                                         HelloWorldFunction-H85Y7yIV7ZLq
------------------------------------------------------------------------------------------------------------------------
```

# sam local callback
<a name="sam-cli-command-reference-sam-local-callback"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam local callback` command.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam local callback` command allows you to send callbacks to local durable function executions during development and testing.

## Usage
<a name="sam-cli-command-reference-sam-local-callback-usage"></a>

```
$ sam local callback <subcommand> <options>
```

## Options
<a name="sam-cli-command-reference-sam-local-callback-options"></a>

`--help, -h`  <a name="sam-cli-command-reference-sam-local-callback-options-help"></a>
Show this message and exit.

## Subcommands
<a name="sam-cli-command-reference-sam-local-callback-subcommands"></a>

`succeed`  <a name="sam-cli-command-reference-sam-local-callback-subcommands-succeed"></a>
Send a success callback to a durable function execution. For more information, see [sam local callback succeed](sam-cli-command-reference-sam-local-callback-succeed.md).

`fail`  <a name="sam-cli-command-reference-sam-local-callback-subcommands-fail"></a>
Send a failure callback to a durable function execution. For more information, see [sam local callback fail](sam-cli-command-reference-sam-local-callback-fail.md).

`heartbeat`  <a name="sam-cli-command-reference-sam-local-callback-subcommands-heartbeat"></a>
Send a heartbeat callback to a durable function execution. For more information, see [sam local callback heartbeat](sam-cli-command-reference-sam-local-callback-heartbeat.md).

# sam local callback succeed
<a name="sam-cli-command-reference-sam-local-callback-succeed"></a>

Send a success callback to a durable function execution.

## Usage
<a name="ref-sam-cli-local-callback-succeed-usage"></a>

```
$ sam local callback succeed CALLBACK_ID [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-local-callback-succeed-arguments"></a>

`CALLBACK_ID`  
The unique identifier of the callback to send a success response to.

## Options
<a name="ref-sam-cli-local-callback-succeed-options"></a>

`-r, --result TEXT`  
Success result payload as string.

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-local-callback-succeed-examples"></a>

Send success callback with no result:

```
$ sam local callback succeed my-callback-id
```

Send success callback with result:

```
$ sam local callback succeed my-callback-id --result 'Task completed successfully'
```

Send success callback with short option:

```
$ sam local callback succeed my-callback-id -r 'Success result'
```

# sam local callback fail
<a name="sam-cli-command-reference-sam-local-callback-fail"></a>

Send a failure callback to a durable function execution.

## Usage
<a name="ref-sam-cli-local-callback-fail-usage"></a>

```
$ sam local callback fail CALLBACK_ID [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-local-callback-fail-arguments"></a>

`CALLBACK_ID`  
The unique identifier of the callback to send a failure response to.

## Options
<a name="ref-sam-cli-local-callback-fail-options"></a>

`--error-data TEXT`  
Additional error data.

`--stack-trace TEXT`  
Stack trace entries. This option can be specified multiple times.

`--error-type TEXT`  
Type of error.

`--error-message TEXT`  
Detailed error message.

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-local-callback-fail-examples"></a>

Send failure callback with no parameters:

```
$ sam local callback fail my-callback-id
```

Send failure callback with error message:

```
$ sam local callback fail my-callback-id --error-message 'Task failed'
```

Send failure callback with all parameters:

```
$ sam local callback fail my-callback-id --error-message 'Task failed' --error-type 'ValidationError' --stack-trace 'at line 42' --error-data '{"code": 500}'
```

# sam local callback heartbeat
<a name="sam-cli-command-reference-sam-local-callback-heartbeat"></a>

Send a heartbeat callback to a durable function execution.

## Usage
<a name="ref-sam-cli-local-callback-heartbeat-usage"></a>

```
$ sam local callback heartbeat CALLBACK_ID [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-local-callback-heartbeat-arguments"></a>

`CALLBACK_ID`  
The unique identifier of the callback to send a heartbeat to.

## Options
<a name="ref-sam-cli-local-callback-heartbeat-options"></a>

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-local-callback-heartbeat-examples"></a>

Send heartbeat callback:

```
$ sam local callback heartbeat my-callback-id
```

# sam local execution
<a name="sam-cli-command-reference-sam-local-execution"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam local execution` command.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam local execution` command allows you to manage and inspect local durable function executions during development and testing.

**Note**  
These commands may not require access to AWS credentials.

## Usage
<a name="sam-cli-command-reference-sam-local-execution-usage"></a>

```
$ sam local execution <subcommand> <options>
```

## Options
<a name="sam-cli-command-reference-sam-local-execution-options"></a>

`--help, -h`  <a name="sam-cli-command-reference-sam-local-execution-options-help"></a>
Show this message and exit.

## Subcommands
<a name="sam-cli-command-reference-sam-local-execution-subcommands"></a>

`get`  <a name="sam-cli-command-reference-sam-local-execution-subcommands-get"></a>
Get details of a durable function execution. For more information, see [sam local execution get](sam-cli-command-reference-sam-local-execution-get.md).

`history`  <a name="sam-cli-command-reference-sam-local-execution-subcommands-history"></a>
Get execution history of a durable function execution. For more information, see [sam local execution history](sam-cli-command-reference-sam-local-execution-history.md).

`stop`  <a name="sam-cli-command-reference-sam-local-execution-subcommands-stop"></a>
Stop a durable function execution. For more information, see [sam local execution stop](sam-cli-command-reference-sam-local-execution-stop.md).

# sam local execution get
<a name="sam-cli-command-reference-sam-local-execution-get"></a>

Retrieve the details of a specific durable function execution.

**Note**  
This command may not require access to AWS credentials.

## Usage
<a name="ref-sam-cli-local-execution-get-usage"></a>

```
$ sam local execution get DURABLE_EXECUTION_ARN [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-local-execution-get-arguments"></a>

`DURABLE_EXECUTION_ARN`  
The Amazon Resource Name (ARN) of the durable function execution to retrieve details for.

## Options
<a name="ref-sam-cli-local-execution-get-options"></a>

`--format [summary|json]`  
Output format. Default: `summary`

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-local-execution-get-examples"></a>

Get execution details with default summary format:

```
$ sam local execution get arn:aws:lambda:us-east-1:123456789012:function:MyFunction:$LATEST/durable-execution/my-execution-name/my-execution-id
```

Get execution details in JSON format:

```
$ sam local execution get arn:aws:lambda:us-east-1:123456789012:function:MyFunction:$LATEST/durable-execution/my-execution-name/my-execution-id --format json
```

# sam local execution history
<a name="sam-cli-command-reference-sam-local-execution-history"></a>

Get execution history of a durable function execution.

## Usage
<a name="ref-sam-cli-local-execution-history-usage"></a>

```
$ sam local execution history EXECUTION_ID [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-local-execution-history-arguments"></a>

`EXECUTION_ID`  
The unique identifier of the durable function execution to retrieve history for.

## Options
<a name="ref-sam-cli-local-execution-history-options"></a>

`--format [table|json]`  
Output format. Default: `table`

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-local-execution-history-examples"></a>

Get execution history in table format:

```
$ sam local execution history my-execution-id
```

Get execution history in JSON format:

```
$ sam local execution history my-execution-id --format json
```

# sam local execution stop
<a name="sam-cli-command-reference-sam-local-execution-stop"></a>

Stop a running durable function execution.

**Note**  
This command may not require access to AWS credentials.

## Usage
<a name="ref-sam-cli-local-execution-stop-usage"></a>

```
$ sam local execution stop DURABLE_EXECUTION_ARN [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-local-execution-stop-arguments"></a>

`DURABLE_EXECUTION_ARN`  
The Amazon Resource Name (ARN) of the durable function execution to stop.

## Options
<a name="ref-sam-cli-local-execution-stop-options"></a>

`--error-message TEXT`  
Error message to associate with the stopped execution.

`--error-type TEXT`  
Error type to associate with the stopped execution.

`--error-data TEXT`  
Error data to associate with the stopped execution.

`--stack-trace TEXT`  
Stack trace entries. This option can be specified multiple times.

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-local-execution-stop-examples"></a>

Stop execution without error details:

```
$ sam local execution stop arn:aws:lambda:us-east-1:123456789012:function:MyFunction:$LATEST/durable-execution/my-execution-name/my-execution-id
```

Stop execution with error message and type:

```
$ sam local execution stop arn:aws:lambda:us-east-1:123456789012:function:MyFunction:$LATEST/durable-execution/my-execution-name/my-execution-id --error-message "Execution cancelled" --error-type "UserCancellation"
```

Stop execution with full error details and stack trace:

```
$ sam local execution stop arn:aws:lambda:us-east-1:123456789012:function:MyFunction:$LATEST/durable-execution/my-execution-name/my-execution-id --error-message "Task failed" --error-type "TaskFailure" --error-data '{"reason":"timeout"}' --stack-trace "at function1()" --stack-trace "at function2()"
```

# sam local generate-event
<a name="sam-cli-command-reference-sam-local-generate-event"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam local generate-event` subcommand.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam local generate-event` command, see [Introduction to testing with sam local generate-event](using-sam-cli-local-generate-event.md).

The `sam local generate-event` subcommand generates event payload samples for supported AWS services.

## Usage
<a name="ref-sam-cli-local-generate-event-usage"></a>

```
$ sam local generate-event <options> <service> <event> <event-options>
```

## Options
<a name="ref-sam-cli-local-generate-event-options"></a>

`--config-env TEXT`  <a name="ref-sam-cli-local-generate-event-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="ref-sam-cli-local-generate-event-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is `samconfig.toml` in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--help`  <a name="ref-sam-cli-local-generate-event-options-help"></a>
Shows this message and exits.

## Service
<a name="ref-sam-cli-local-generate-event-service"></a>

To see a list of supported services, run the following:

```
$ sam local generate-event
```

## Event
<a name="ref-sam-cli-local-generate-event-event"></a>

To see a list of supported events that can be generated for each service, run the following:

```
$ sam local generate-event <service>
```

## Event options
<a name="ref-sam-cli-local-generate-event-event-options"></a>

To see a list of supported event options that you can modify, run the following:

```
$ sam local generate-event <service> <event> --help
```

## Examples
<a name="sam-cli-command-reference-sam-local-generate-event-examples"></a>

For examples on using the `sam local generate-event` subcommand, refer to [Generate sample events](using-sam-cli-local-generate-event.md#using-sam-cli-local-generate-event-generate).

# sam local invoke
<a name="sam-cli-command-reference-sam-local-invoke"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam local invoke` subcommand.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam local invoke` subcommand, see [Introduction to testing with sam local invoke](using-sam-cli-local-invoke.md).

The `sam local invoke` subcommand initiates a one-time invocation of an AWS Lambda function locally.

**Note**  
It's not recommended to use SAM CLI's local invoke capabilities in untrusted code. To have complete isolation from your local environment, execute the code in the Lambda service directly.

**Note**  
For durable functions, `sam local invoke` supports stateful execution with automatic checkpointing and replay. The container remains running during durable function execution to handle state persistence and resumption.

## Usage
<a name="ref-sam-cli-local-invoke-usage"></a>

```
$ sam local invoke <arguments> <options>
```

**Note**  
If you have more than one function defined in your AWS SAM template, provide the function logical ID that you want to invoke.

## Arguments
<a name="ref-sam-cli-local-invoke-args"></a>

**Resource ID**  <a name="ref-sam-cli-local-invoke-args-resource-id"></a>
The ID of the Lambda function to invoke.  
This argument is optional. If your application contains a single Lambda function, the AWS SAM CLI will invoke it. If your application contains multiple functions, provide the ID of the function to invoke.  
*Valid values*: The resource's logical ID or resource ARN.

## Options
<a name="ref-sam-cli-local-invoke-options"></a>

`--add-host LIST`  <a name="ref-sam-cli-local-invoke-options-add-host"></a>
Passes a hostname to IP address mapping to the Docker container's host file. This parameter can be passed multiple times.  

**Example**  
Example: `--add-host example.com:127.0.0.1`

`--beta-features | --no-beta-features`  <a name="ref-sam-cli-local-invoke-options-beta-features"></a>
Allow or deny beta features.

`--config-env TEXT`  <a name="ref-sam-cli-local-invoke-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="ref-sam-cli-local-invoke-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "`samconfig.toml`" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--container-env-vars`  <a name="ref-sam-cli-local-invoke-options-container-env-vars"></a>
(Optional) Pass environment variables to the Lambda function image container when debugging locally.

`--container-host TEXT`  <a name="ref-sam-cli-local-invoke-options-container-host"></a>
Host of locally emulated Lambda container. The default value is `localhost`. If you want to run AWS SAM CLI in a Docker container on macOS, you can specify `host.docker.internal`. If you want to run the container on a different host than AWS SAM CLI, you can specify the IP address of the remote host.

`--container-host-interface TEXT`  <a name="ref-sam-cli-local-invoke-options-container-host-interface"></a>
The IP address of the host network interface that container ports should bind to. The default value is `127.0.0.1`. Use `0.0.0.0` to bind to all interfaces.

`--debug`  <a name="ref-sam-cli-local-invoke-options-debug"></a>
Turns on debug logging to print debug messages that the AWS SAM CLI generates, and to display timestamps.

`--debug-args TEXT`  <a name="ref-sam-cli-local-invoke-options-debug-args"></a>
Additional arguments to pass to the debugger.

`--debug-port, -d TEXT`  <a name="ref-sam-cli-local-invoke-options-debug-port"></a>
When specified, starts the Lambda function container in debug mode and exposes this port on the local host.

`--debugger-path TEXT`  <a name="ref-sam-cli-local-invoke-options-debugger-path"></a>
The host path to a debugger that's mounted into the Lambda container.

`--docker-network TEXT`  <a name="ref-sam-cli-local-invoke-options-docker-network"></a>
The name or ID of an existing Docker network that Lambda Docker containers should connect to, along with the default bridge network. If this isn't specified, the Lambda containers connect only to the default bridge Docker network.

`--docker-volume-basedir, -v TEXT`  <a name="ref-sam-cli-local-invoke-options-docker-volume-basedir"></a>
The location of the base directory where the AWS SAM file exists. If Docker is running on a remote machine, you must mount the path where the AWS SAM file exists on the Docker machine and modify this value to match the remote machine.

`--durable-execution-name TEXT`  <a name="ref-sam-cli-local-invoke-options-durable-execution-name"></a>
Name for the durable execution (for durable functions only)

`--env-vars, -n PATH`  <a name="ref-sam-cli-local-invoke-options-env-vars"></a>
The JSON or `.env` file that contains values for the Lambda function's environment variables. The file format is automatically detected. For more information about environment variable files, see [Environment variable file](serverless-sam-cli-using-invoke.md#serverless-sam-cli-using-invoke-environment-file).

`--event, -e PATH`  <a name="ref-sam-cli-local-invoke-options-event"></a>
The JSON file that contains event data that's passed to the Lambda function when it's invoked. If you don't specify this option, no event is assumed. To input JSON from `stdin`, you must pass in the value '-'. For details about event message formats from different AWS services, see [Working with other services](https://docs.aws.amazon.com/lambda/latest/dg/lambda-services.html) in the *AWS Lambda Developer Guide*.

`--force-image-build`  <a name="ref-sam-cli-local-invoke-options-force-image-build"></a>
Specifies whether the AWS SAM CLI should rebuild the image used for invoking Lambda functions with layers.

`--help`  <a name="ref-sam-cli-local-invoke-options-help"></a>
Shows this message and exits.

`--hook-name TEXT`  <a name="ref-sam-cli-local-invoke-options-hook-name"></a>
The name of the hook that is used to extend AWS SAM CLI functionality.  
Accepted values: `terraform`.

`--invoke-image TEXT`  <a name="ref-sam-cli-local-invoke-options-invoke-image"></a>
The URI of the container image that you want to use for the local function invocation. By default, AWS SAM pulls the container image from Amazon ECR Public (which are listed in [Image repositories for AWS SAM](serverless-image-repositories.md)). Use this option to pull the image from another location.  
For example, `sam local invoke MyFunction --invoke-image amazon/aws-sam-cli-emulation-image-python3.8`.

`--layer-cache-basedir DIRECTORY`  <a name="ref-sam-cli-local-invoke-options-layer-cache-basedir"></a>
Specifies the location of the base directory where the layers that your template uses are downloaded to.

`--log-file, -l TEXT`  <a name="ref-sam-cli-local-invoke-options-log-file"></a>
The log file to send runtime logs to.

`--mount-symlinks`  <a name="ref-sam-cli-local-invoke-options-mount-symlinks"></a>
Ensures the AWS SAM CLI always mounts symlinks that are present in the files to build or invoke. This applies only to symlinks on the top level directory (that is, symlinks that are directly on the function's root). By default, symlinks are not mounted except for those needed to use `build-in-source` for `node_modules` in NodeJS.

`--no-event`  <a name="ref-sam-cli-local-invoke-options-no-event"></a>
Invokes the function with an empty event.

`--no-memory-limit`  <a name="ref-sam-cli-local-invoke-options-no-memory-limit"></a>
Removes the memory limitation in the container during local invoke, even when memory is configured in the AWS SAM template.

`--parameter-overrides`  <a name="ref-sam-cli-local-invoke-options-parameter-overrides"></a>
A string that contains CloudFormation parameter overrides encoded as key-value pairs. Use the same format as the AWS Command Line Interface (AWS CLI). The AWS SAM CLI format is explicit key and value keywords, each override is separated by a space. Here are two examples:  
+ `--parameter-overrides ParameterKey=hello,ParameterValue=world`
+ `--parameter-overrides ParameterKey=hello,ParameterValue=world ParameterKey=example1,ParameterValue=example2 ParameterKey=apple,ParameterValue=banana`

`--profile TEXT`  <a name="ref-sam-cli-local-invoke-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="ref-sam-cli-local-invoke-options-region"></a>
The AWS Region to deploy to. For example, us-east-1.

`--runtime TEXT`  <a name="ref-sam-cli-local-invoke-options-runtime"></a>
Uses the specified runtime to invoke a Lambda function locally. This overrides the runtime defined in the `template.yml` file. This also allows testing Lambda functions with different runtimes without modifying the original function configuration.

`--save-params`  <a name="ref-sam-cli-local-invoke-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--shutdown`  <a name="ref-sam-cli-local-invoke-options-shutdown"></a>
Emulates a shutdown event after the invoke completes, in order to test extension handling of shutdown behavior.

`--skip-prepare-infra`  <a name="ref-sam-cli-local-invoke-options-skip-prepare-infra"></a>
Skips the preparation stage if no infrastructure changes have been made. Use with the `--hook-name` option.

`--skip-pull-image`  <a name="ref-sam-cli-local-invoke-options-skip-pull-image"></a>
By default, the AWS SAM CLI checks Lambda's latest remote runtime environment and updates your local image automatically to keep in sync.  
Specify this option to skip pulling down the latest Docker image for your Lambda runtime environment.

`--template, -t PATH`  <a name="ref-sam-cli-local-invoke-options-template"></a>
The AWS SAM template file.  
This option is not compatible with `--hook-name`.  
If you specify this option, AWS SAM loads only the template and the local resources that it points to.

`--tenant-id TEXT`  <a name="ref-sam-cli-local-invoke-options-tenancyconfig"></a>
The tenant ID for multi-tenant Lambda functions. Used to ensure compute isolation between different tenants. Required when invoking functions configured with tenant isolation mode.

`--terraform-plan-file`  <a name="ref-sam-cli-local-invoke-options-terraform-plan-file"></a>
The relative or absolute path to your local Terraform plan file when using the AWS SAM CLI with Terraform Cloud. This option requires that `--hook-name` be set to `terraform`.

## Examples
<a name="sam-cli-command-reference-sam-local-invoke-examples"></a>

The following example uses a generated event for local testing by using an `s3.json` event to invoke a Lambda function locally

```
$ sam local invoke --event events/s3.json S3JsonLoggerFunction
```

The following example tests the function ` HelloWorldFunction` using Python 3.11 runtime

```
$ sam local invoke --runtime python3.11 HelloWorldFunction
```

The following example tests the function ` HelloWorldFunction` with durable execution name

```
$ sam local invoke HelloWorldFunction --durable-execution-name my-execution
```

# sam local start-api
<a name="sam-cli-command-reference-sam-local-start-api"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam local start-api` subcommand.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam local start-api` subcommand, see [Introduction to testing with sam local start-api](using-sam-cli-local-start-api.md).

The `sam local start-api` subcommand runs your AWS Lambda functions locally to test through a local HTTP server host.

## Usage
<a name="ref-sam-cli-local-start-api-usage"></a>

```
$ sam local start-api <options>
```

## Options
<a name="ref-sam-cli-local-start-api-options"></a>

`--add-host LIST`  <a name="ref-sam-cli-local-start-api-options-add-host"></a>
Passes a hostname to IP address mapping to the Docker container's host file. This parameter can be passed multiple times.  

**Example**  
Example: `--add-host example.com:127.0.0.1`

`--beta-features | --no-beta-features`  <a name="ref-sam-cli-local-start-api-options-beta-features"></a>
Allow or deny beta features.

`--config-env TEXT`  <a name="ref-sam-cli-local-start-api-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="ref-sam-cli-local-start-api-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "samconfig.toml" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--container-env-vars`  <a name="ref-sam-cli-local-start-api-options-container-env-vars"></a>
Optional. Pass environment variables to image container when locally debugging.

`--container-host TEXT`  <a name="ref-sam-cli-local-start-api-options-container-host"></a>
Host of locally emulated Lambda container. The default value is `localhost`. If you want to run AWS SAM CLI in a Docker container on macOS, you can specify `host.docker.internal`. If you want to run the container on a different host than AWS SAM CLI, you can specify the IP address of the remote host.

`--container-host-interface TEXT`  <a name="ref-sam-cli-local-start-api-options-container-host-interface"></a>
The IP address of the host network interface that container ports should bind to. The default value is `127.0.0.1`. Use `0.0.0.0` to bind to all interfaces.

`--debug`  <a name="ref-sam-cli-local-start-api-options-debug"></a>
Turns on debug logging to print debug message generated by the AWS SAM CLI and display timestamps.

`--debug-args TEXT`  <a name="ref-sam-cli-local-start-api-options-debug-args"></a>
Additional arguments to be passed to the debugger.

`--debug-function`  <a name="ref-sam-cli-local-start-api-options-debug-function"></a>
Optional. Specifies the Lambda function to apply debug options to when `--warm-containers` is specified. This parameter applies to `--debug-port`, `--debugger-path`, and `--debug-args`.

`--debug-port, -d TEXT`  <a name="ref-sam-cli-local-start-api-options-debug-port"></a>
When specified, starts the Lambda function container in debug mode and exposes this port on the local host.

`--debugger-path TEXT`  <a name="ref-sam-cli-local-start-api-options-debugger-path"></a>
The host path to a debugger that will be mounted into the Lambda container.

`--docker-network TEXT`  <a name="ref-sam-cli-local-start-api-options-docker-network"></a>
The name or ID of an existing Docker network that the Lambda Docker containers should connect to, along with the default bridge network. If this isn't specified, the Lambda containers only connect to the default bridge Docker network.

` --docker-volume-basedir, -v TEXT`  <a name="ref-sam-cli-local-start-api-options-docker-volume-basedir"></a>
The location of the base directory where the AWS SAM file exists. If Docker is running on a remote machine, you must mount the path where the AWS SAM file exists on the Docker machine, and modify this value to match the remote machine.

`--env-vars, -n PATH`  <a name="ref-sam-cli-local-start-api-options-env-vars"></a>
The JSON or `.env` file that contains values for the Lambda function's environment variables. The file format is automatically detected.

`--force-image-build`  <a name="ref-sam-cli-local-start-api-options-force-image-build"></a>
Specifies whether AWS SAM CLI should rebuild the image used for invoking functions with layers.

`--help`  <a name="ref-sam-cli-local-start-api-options-help"></a>
Shows this message and exits.

`--hook-name TEXT`  <a name="ref-sam-cli-local-start-api-options-hook-name"></a>
The name of the hook that is used to extend AWS SAM CLI functionality.  
Accepted values: `terraform`.

`--host TEXT`  <a name="ref-sam-cli-local-start-api-options-host"></a>
The local hostname or IP address to bind to (default: '127.0.0.1').

`--invoke-image TEXT`  <a name="ref-sam-cli-local-start-api-options-invoke-image"></a>
The URI of the container image that you want to use for your Lambda functions. By default, AWS SAM pulls the container image from Amazon ECR Public. Use this option to pull the image from another location.  
You can specify this option multiple times. Each instance of this option can take either a string or a key-value pair. If you specify a string, it is the URI of the container image to use for all functions in your application. For example, `sam local start-api --invoke-image public.ecr.aws/sam/emu-python3.8`. If you specify a key-value pair, the key is the resource name, and the value is the URI of the container image to use for that resource. For example `sam local start-api --invoke-image public.ecr.aws/sam/emu-python3.8 --invoke-image Function1=amazon/aws-sam-cli-emulation-image-python3.8 `. With key-value pairs, you can specify different container images for different resources.

`--layer-cache-basedir DIRECTORY`  <a name="ref-sam-cli-local-start-api-options-layer-cache-basedir"></a>
Specifies the location basedir where the Layers your template uses are downloaded to.

`--log-file, -l TEXT`  <a name="ref-sam-cli-local-start-api-options-log-file"></a>
The log file to send runtime logs to.

`--no-memory-limit`  <a name="ref-sam-cli-local-start-api-options-no-memory-limit"></a>
Removes the memory limitation in the container during local invoke, even when memory is configured in the AWS SAM template.

`--parameter-overrides`  <a name="ref-sam-cli-local-start-api-options-parameter-overrides"></a>
A string that contains CloudFormation parameter overrides encoded as key-value pairs. Use the same format as the AWS Command Line Interface (AWS CLI). The AWS SAM CLI format is explicit key and value keywords, each override is separated by a space. Here are two examples:  
+ `--parameter-overrides ParameterKey=hello,ParameterValue=world`
+ `--parameter-overrides ParameterKey=hello,ParameterValue=world ParameterKey=example1,ParameterValue=example2 ParameterKey=apple,ParameterValue=banana`

`--port, -p INTEGER`  <a name="ref-sam-cli-local-start-api-options-port"></a>
The local port number to listen on (default: '3000').

`--profile TEXT`  <a name="ref-sam-cli-local-start-api-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="ref-sam-cli-local-start-api-options-region"></a>
The AWS Region to deploy to. For example, us-east-1.

`--save-params`  <a name="ref-sam-cli-local-start-api-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--shutdown`  <a name="ref-sam-cli-local-start-api-options-shutdown"></a>
Emulates a shutdown event after the invoke completes, in order to test extension handling of shutdown behavior.

`--skip-prepare-infra`  <a name="ref-sam-cli-local-start-api-options-skip-prepare-infra"></a>
Skips the preparation stage if no infrastructure changes have been made. Use with the `--hook-name` option.

`--skip-pull-image`  <a name="ref-sam-cli-local-start-api-options-skip-pull-image"></a>
Specifies whether the CLI should skip pulling down the latest Docker image for the Lambda runtime.

`--ssl-cert-file PATH`  <a name="ref-sam-cli-local-start-api-options-ssl-cert-file"></a>
Path to SSL certificate file (default: None). When using this option, the `--ssl-key-file` option must also be used.

`--ssl-key-file PATH`  <a name="ref-sam-cli-local-start-api-options-static-dir"></a>
Path to SSL key file (default: None). When using this option, the `--ssl-cert-file` option must also be used.

`--static-dir, -s TEXT`  <a name="ref-sam-cli-local-start-api-options-static-dir"></a>
Any static asset (for example, CSS/JavaScript/HTML) files located in this directory are presented at `/`.

`--template, -t PATH`  <a name="ref-sam-cli-local-start-api-options-template"></a>
The AWS SAM template file.  
If you specify this option, AWS SAM loads only the template and the local resources that it points to.

`--terraform-plan-file`  <a name="ref-sam-cli-local-start-api-options-terraform-plan-file"></a>
The relative or absolute path to your local Terraform plan file when using the AWS SAM CLI with Terraform Cloud. This option requires that `--hook-name` be set to `terraform`.

`--warm-containers [EAGER | LAZY]`  <a name="ref-sam-cli-local-start-api-options-warm-containers"></a>
Optional. Specifies how AWS SAM CLI manages containers for each function.  
Two options are available:  
   `EAGER`: Containers for all functions are loaded at startup and persist between invocations.  
   `LAZY`: Containers are only loaded when each function is first invoked. Those containers persist for additional invocations.

## Example
<a name="sam-cli-command-reference-sam-local-start-api-examples"></a>

The following example starts a local server, allowing you to test your application via API. For this command to work, the application must be installed and Docker must be running.

```
$ sam local start-api --port 3000
```

# sam local start-lambda
<a name="sam-cli-command-reference-sam-local-start-lambda"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam local start-lambda` subcommand.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam local start-lambda` subcommand, see [Introduction to testing with sam local start-lambda](using-sam-cli-local-start-lambda.md).

The `sam local start-lambda` subcommand starts a local endpoint to emulate AWS Lambda.

## Usage
<a name="ref-sam-cli-local-start-lambda-usage"></a>

```
$ sam local start-lambda <options>
```

## Options
<a name="ref-sam-cli-local-start-lambda-options"></a>

`--add-host LIST`  <a name="ref-sam-cli-local-start-lambda-options-add-host"></a>
Passes a hostname to IP address mapping to the Docker container's host file. This parameter can be passed multiple times.  

**Example**  
Example: `--add-host example.com:127.0.0.1`

`--beta-features | --no-beta-features`  <a name="ref-sam-cli-local-start-lambda-options-beta-features"></a>
Allow or deny beta features.

`--config-env TEXT`  <a name="ref-sam-cli-local-start-lambda-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="ref-sam-cli-local-start-lambda-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "samconfig.toml" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--container-env-vars`  <a name="ref-sam-cli-local-start-lambda-options-container-env-vars"></a>
Optional. Pass environment variables to image container when locally debugging.

`--container-host TEXT`  <a name="ref-sam-cli-local-start-lambda-options-container-host"></a>
Host of locally emulated Lambda container. The default value is `localhost`. If you want to run AWS SAM CLI in a Docker container on macOS, you can specify `host.docker.internal`. If you want to run the container on a different host than AWS SAM CLI, you can specify the IP address of the remote host.

`--container-host-interface TEXT`  <a name="ref-sam-cli-local-start-lambda-options-container-host-interface"></a>
The IP address of the host network interface that container ports should bind to. The default value is `127.0.0.1`. Use `0.0.0.0` to bind to all interfaces.

`--debug`  <a name="ref-sam-cli-local-start-lambda-options-debug"></a>
Turns on debug logging to print debug message generated by the AWS SAM CLI and display timestamps.

`--debug-args TEXT`  <a name="ref-sam-cli-local-start-lambda-options-debug-args"></a>
Additional arguments to be passed to the debugger.

`--debug-function`  <a name="ref-sam-cli-local-start-lambda-options-debug-function"></a>
Optional. Specifies the Lambda function to apply debug options to when `--warm-containers` is specified. This parameter applies to `--debug-port`, `--debugger-path`, and `--debug-args`.

`--debug-port, -d TEXT`  <a name="ref-sam-cli-local-start-lambda-options-debug-port"></a>
When specified, starts the Lambda function container in debug mode, and exposes this port on the local host.

`--debugger-path TEXT`  <a name="ref-sam-cli-local-start-lambda-options-debugger-path"></a>
The host path to a debugger to be mounted into the Lambda container.

`--docker-network TEXT`  <a name="ref-sam-cli-local-start-lambda-options-docker-network"></a>
The name or ID of an existing Docker network that Lambda Docker containers should connect to, along with the default bridge network. If this is specified, the Lambda containers only connect to the default bridge Docker network.

`--docker-volume-basedir, -v TEXT`  <a name="ref-sam-cli-local-start-lambda-options-docker-volume-basedir"></a>
The location of the base directory where the AWS SAM file exists. If Docker is running on a remote machine, you must mount the path where the AWS SAM file exists on the Docker machine, and modify this value to match the remote machine.

`--env-vars, -n PATH`  <a name="ref-sam-cli-local-start-lambda-options-env-vars"></a>
The JSON or `.env` file that contains values for the Lambda function's environment variables. The file format is automatically detected.

`--force-image-build`  <a name="ref-sam-cli-local-start-lambda-options-force-image-build"></a>
Specify whether the CLI should rebuild the image used for invoking functions with layers.

`--help`  <a name="ref-sam-cli-local-start-lambda-options-help"></a>
Shows this message and exits.

`--hook-name TEXT`  <a name="ref-sam-cli-local-start-lambda-options-hook-name"></a>
The name of the hook that is used to extend AWS SAM CLI functionality.  
Accepted values: `terraform`.

`--host TEXT`  <a name="ref-sam-cli-local-start-lambda-options-host"></a>
The local hostname or IP address to bind to (default: '127.0.0.1').

`--invoke-image TEXT`  <a name="ref-sam-cli-local-start-lambda-options-invoke-image"></a>
The URI of the container image that you want to use for the local function invocation. By default, AWS SAM pulls the container image from Amazon ECR Public. Use this option to pull the image from another location.  
For example, `sam local start-lambda MyFunction --invoke-image amazon/aws-sam-cli-emulation-image-python3.8`.

`--layer-cache-basedir DIRECTORY`  <a name="ref-sam-cli-local-start-lambda-options-layer-cache-basedir"></a>
Specifies the location basedir where the layers your template uses are downloaded to.

`--log-file, -l TEXT`  <a name="ref-sam-cli-local-start-lambda-options-log-file"></a>
The log file to send runtime logs to.

`--no-memory-limit`  <a name="ref-sam-cli-local-start-lambda-options-no-memory-limit"></a>
Removes the memory limitation in the container during local invoke, even when memory is configured in the AWS SAM template.

`--parameter-overrides`  <a name="ref-sam-cli-local-start-lambda-options-parameter-overrides"></a>
A string that contains CloudFormation parameter overrides encoded as key-value pairs. Use the same format as the AWS Command Line Interface (AWS CLI). The AWS SAM CLI format is explicit key and value keywords, each override is separated by a space. Here are two examples:  
+ `--parameter-overrides ParameterKey=hello,ParameterValue=world`
+ `--parameter-overrides ParameterKey=hello,ParameterValue=world ParameterKey=example1,ParameterValue=example2 ParameterKey=apple,ParameterValue=banana`

`--port, -p INTEGER`  <a name="ref-sam-cli-local-start-lambda-options-port"></a>
The local port number to listen on (default: '3001').

`--profile TEXT`  <a name="ref-sam-cli-local-start-lambda-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="ref-sam-cli-local-start-lambda-options-region"></a>
The AWS Region to deploy to. For example, us-east-1.

`--save-params`  <a name="ref-sam-cli-local-start-lambda-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--shutdown`  <a name="ref-sam-cli-local-start-lambda-options-shutdown"></a>
Emulates a shutdown event after the invoke completes, in order to test extension handling of shutdown behavior.

`--skip-prepare-infra`  <a name="ref-sam-cli-local-start-lambda-options-skip-prepare-infra"></a>
Skips the preparation stage if no infrastructure changes have been made. Use with the `--hook-name` option.

`--skip-pull-image`  <a name="ref-sam-cli-local-start-lambda-options-skip-pull-image"></a>
Specifies whether the CLI should skip pulling down the latest Docker image for the Lambda runtime.

`--template, -t PATH`  <a name="ref-sam-cli-local-start-lambda-options-template"></a>
The AWS SAM template file.  
If you specify this option, AWS SAM loads only the template and the local resources that it points to. This option is not compatible with `--hook-name`.

`--terraform-plan-file`  <a name="ref-sam-cli-local-start-lambda-options-terraform-plan-file"></a>
The relative or absolute path to your local Terraform plan file when using the AWS SAM CLI with Terraform Cloud. This option requires that `--hook-name` be set to `terraform`.

`--warm-containers [EAGER | LAZY]`  <a name="ref-sam-cli-local-start-lambda-options-warm-containers"></a>
Optional. Specifies how AWS SAM CLI manages containers for each function.  
Two options are available:  
+ `EAGER`: Containers for all functions are loaded at startup and persist between invocations.
+ `LAZY`: Containers are only loaded when each function is first invoked. Those containers persist for additional invocations.

## Example
<a name="sam-cli-command-reference-sam-local-start-lambda-examples"></a>

For a detailed example and in-depth walkthrough on using the `sam local start-lambda` subcommand, refer to [Introduction to testing with sam local start-lambda](using-sam-cli-local-start-lambda.md).

# sam logs
<a name="sam-cli-command-reference-sam-logs"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam logs` command.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam logs` command fetches logs that are generated by your AWS Lambda functions.

## Usage
<a name="sam-cli-command-reference-sam-logs-usage"></a>

```
$ sam logs <options>
```

## Options
<a name="sam-cli-command-reference-sam-logs-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-logs-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-sam-logs-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "samconfig.toml" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--cw-log-group LIST`  <a name="sam-cli-command-reference-sam-logs-options-cw-log-group"></a>
Includes logs from the CloudWatch Logs log groups that you specify. If you specify this option along with `name`, AWS SAM includes logs from the specified log groups in addition to logs from the named resources.

`--debug`  <a name="sam-cli-command-reference-sam-logs-options-debug"></a>
Turns on debug logging to print debug message generated by the AWS SAM CLI and display timestamps.

`---end-time, e TEXT`  <a name="sam-cli-command-reference-sam-logs-options-end-time"></a>
Fetches logs up to this time. The time can be relative values like '5mins ago', 'tomorrow', or a formatted timestamp like '2018-01-01 10:10:10'.

`--filter TEXT`  <a name="sam-cli-command-reference-sam-logs-options-filter"></a>
Lets you specify an expression to quickly find logs that match terms, phrases, or values in your log events. This can be a simple keyword (for example, "error") or a pattern that's supported by Amazon CloudWatch Logs. For the syntax, see the [Amazon CloudWatch Logs documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html).

`--help`  <a name="sam-cli-command-reference-sam-logs-options-help"></a>
Shows this message and exits.

`--include-traces`  <a name="sam-cli-command-reference-sam-logs-options-include-traces"></a>
Includes X-Ray traces in the log output.

`--name, -n TEXT`  <a name="sam-cli-command-reference-sam-logs-options-name"></a>
The name of the resource for which to fetch logs. If this resource is part of an CloudFormation stack, this can be the logical ID of the function resource in the CloudFormation/AWS SAM template. Multiple names can be provided by repeating the parameter again. If resource is in a nested stack, the name can be prepended by the name of the nested stack name to pull logs from that resource (NestedStackLogicalId/ResourceLogicalId). If the resource name isn't given, the given stack will be scanned and log information will be pulled for all supported resources. If you don't specify this option, AWS SAM fetches logs for all resources in the stack that you specify. The following resource types are supported:  
+ `AWS::Serverless::Function`
+ `AWS::Lambda::Function`
+ `AWS::Serverless::Api`
+ `AWS::ApiGateway::RestApi`
+ `AWS::Serverless::HttpApi`
+ `AWS::ApiGatewayV2::Api`
+ `AWS::Serverless::StateMachine`
+ `AWS::StepFunctions::StateMachine`

`--output TEXT`  <a name="sam-cli-command-reference-sam-logs-options-output"></a>
Specifies the output format for logs. To print formatted logs, specify `text`. To print the logs as JSON, specify `json`.

`--profile TEXT`  <a name="sam-cli-command-reference-sam-logs-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="sam-cli-command-reference-sam-logs-options-region"></a>
The AWS Region to deploy to. For example, us-east-1.

`--save-params`  <a name="sam-cli-command-reference-sam-logs-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--stack-name TEXT`  <a name="sam-cli-command-reference-sam-logs-options-stack-name"></a>
The name of the CloudFormation stack that the resource is a part of.

`--start-time, -s TEXT`  <a name="sam-cli-command-reference-sam-logs-options-start-time"></a>
Fetches logs starting at this time. The time can be relative values like '5mins ago', 'yesterday', or a formatted timestamp like '2018-01-01 10:10:10'. It defaults to '10mins ago'.

` --tail, -t`  <a name="sam-cli-command-reference-sam-logs-options-tail"></a>
Tails the log output. This ignores the end time argument and continues to fetch logs as they become available.

## Examples
<a name="sam-cli-command-reference-sam-logs-examples"></a>

When your functions are a part of an CloudFormation stack, you can fetch logs by using the function's logical ID when you specify the stack name.

```
$ sam logs -n HelloWorldFunction --stack-name myStack
```

View logs for a specific time range using the -s (--start-time) and -e (--end-time) options.

```
$ sam logs -n HelloWorldFunction --stack-name myStack -s '10min ago' -e '2min ago'
```

You can also add the `--tail` option to wait for new logs and see them as they arrive.

```
$ sam logs -n HelloWorldFunction --stack-name myStack --tail
```

Use the `--filter` option to quickly find logs that match terms, phrases or values in your log events.

```
$ sam logs -n HelloWorldFunction --stack-name myStack --filter "error"
```

View the logs for a resource in a child stack.

```
$ sam logs --stack-name myStack -n childStack/HelloWorldFunction
```

Tail logs for all supported resources in your application.

```
$ sam logs --stack-name sam-app --tail
```

Fetch logs for a specific Lambda function and API Gateway API in your application.

```
$ sam logs --stack-name sam-app --name HelloWorldFunction --name HelloWorldRestApi
```

Fetch logs for all supported resources in your application, and additionally from the specified log groups.

```
$ sam logs --cw-log-group /aws/lambda/myfunction-123 --cw-log-group /aws/lambda/myfunction-456
```

# sam package
<a name="sam-cli-command-reference-sam-package"></a>

The AWS Serverless Application Model Command Line Interface (AWS SAM CLI) packages an AWS SAM application.

This command creates a `.zip` file of your code and dependencies, and uploads the file to Amazon Simple Storage Service (Amazon S3). AWS SAM enables encryption for all files stored in Amazon S3. It then returns a copy of your AWS SAM template, replacing references to local artifacts with the Amazon S3 location where the command uploaded the artifacts.

By default when you use this command, the AWS SAM CLI assumes that your current working directory is your project's root directory. The AWS SAM CLI first tries to locate a template file built using the [sam build](sam-cli-command-reference-sam-build.md) command, located in the `.aws-sam` subfolder, and named `template.yaml`. Next, the AWS SAM CLI tries to locate a template file named `template.yaml` or `template.yml` in the current working directory. If you specify the `--template` option, AWS SAM CLI's default behavior is overridden, and will package just that AWS SAM template and the local resources it points to.

**Note**  
[sam deploy](sam-cli-command-reference-sam-deploy.md) now implicitly performs the functionality of `sam package`. You can use the [sam deploy](sam-cli-command-reference-sam-deploy.md) command directly to package and deploy your application.

## Usage
<a name="sam-cli-command-reference-sam-package-usage"></a>

```
$ sam package <arguments> <options>
```

## Arguments
<a name="sam-cli-command-reference-sam-package-args"></a>

**Resource ID**  <a name="sam-cli-command-reference-sam-package-args-resource-id"></a>
The ID of the Lambda function to package.  
This argument is optional. If your application contains a single Lambda function, the AWS SAM CLI will package it. If your application contains multiple functions, provide the ID of the function to package a single function.  
*Valid values*: The resource's logical ID or resource ARN.

## Options
<a name="sam-cli-command-reference-sam-package-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-package-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-sam-package-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "samconfig.toml" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--debug`  <a name="sam-cli-command-reference-sam-package-options-debug"></a>
Turns on debug logging to print debug message generated by the AWS SAM CLI and display timestamps.

`--force-upload`  <a name="sam-cli-command-reference-sam-package-options-force-upload"></a>
Override existing files in the Amazon S3 bucket. Specify this flag to upload artifacts even if they match existing artifacts in the Amazon S3 bucket.

`--help`  <a name="sam-cli-command-reference-sam-package-options-help"></a>
Shows this message and exits.

`--image-repository TEXT`  <a name="sam-cli-command-reference-sam-package-options-image-repository"></a>
The URI of the Amazon Elastic Container Registry (Amazon ECR) repository where this command uploads your function's image. Required for functions declared with the `Image` package type.

`--kms-key-id TEXT`  <a name="sam-cli-command-reference-sam-package-options-kms-key-id"></a>
The ID of an AWS Key Management Service (AWS KMS) key used to encrypt artifacts that are at rest in the Amazon S3 bucket. If this option is not specified, then AWS SAM uses Amazon S3-managed encryption keys.

`--metadata`  <a name="sam-cli-command-reference-sam-package-options-metadata"></a>
(Optional) A map of metadata to attach to all artifacts that are referenced in your template.

`--no-progressbar`  <a name="sam-cli-command-reference-sam-package-options-no-progressbar"></a>
Do not display a progress bar when uploading artifacts to Amazon S3.

`--output-template-file PATH`  <a name="sam-cli-command-reference-sam-package-options-output-template-file"></a>
The path to the file where the command writes the packaged template. If you don't specify a path, the command writes the template to the standard output.

`--profile TEXT`  <a name="sam-cli-command-reference-sam-package-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="sam-cli-command-reference-sam-package-options-region"></a>
The AWS Region to deploy to. For example, us-east-1.

`--resolve-s3`  <a name="sam-cli-command-reference-sam-package-options-resolve-s3"></a>
Automatically create an Amazon S3 bucket to use for packaging. If you specify both the `--s3-bucket` and `--resolve-s3` options, then an error will result.

`--s3-bucket TEXT`  <a name="sam-cli-command-reference-sam-package-options-s3-bucket"></a>
The name of the Amazon S3 bucket where this command uploads your artifact. If your artifact is larger than 51,200 bytes, then either the `--s3-bucket` or the `--resolve-s3` option is required. If you specify both the `--s3-bucket` and `--resolve-s3` options, then an error will result.

`--s3-prefix TEXT`  <a name="sam-cli-command-reference-sam-package-options-s3-prefix"></a>
Prefix added to the artifacts name that are uploaded to the Amazon S3 bucket. The prefix name is a path name (folder name) for the Amazon S3 bucket. This only applies for functions declared with `Zip` package type.

`--save-params`  <a name="sam-cli-command-reference-sam-package-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--signing-profiles LIST`  <a name="sam-cli-command-reference-sam-package-options-signing-profiles"></a>
(Optional) The list of signing profiles to sign your deployment packages with. This parameter takes a list of key-value pairs, where the key is the name of the function or layer to sign, and the value is the signing profile, with an optional profile owner delimited with `:`. For example, `FunctionNameToSign=SigningProfileName1 LayerNameToSign=SigningProfileName2:SigningProfileOwner`.

`--template-file, --template, -t PATH`  <a name="sam-cli-command-reference-sam-package-options-template-file"></a>
The path and file name where your AWS SAM template is located.  
If you specify this option, AWS SAM packages only the template and the local resources that it points to.

`--use-json`  <a name="sam-cli-command-reference-sam-package-options-use-json"></a>
Output JSON for the CloudFormation template. YAML is used by default.

## Example
<a name="sam-cli-command-reference-sam-package-examples"></a>

The following example creates and packages artifacts for a Lambda function and CodeDeploy applications. Artifacts are uploaded to an Amazon S3 bucket. The output of the command is a new file called `package.yml`.

```
$ sam package \
  --template-file template.yml \
  --output-template-file package.yml \
  --s3-bucket amzn-s3-demo-bucket
```

# sam pipeline bootstrap
<a name="sam-cli-command-reference-sam-pipeline-bootstrap"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam local pipeline bootstrap` subcommand.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam pipeline bootstrap` subcommand generates the required AWS infrastructure resources to connect to your CI/CD system. This step must be run for each deployment stage in your pipeline prior to running the **sam pipeline init** command.

This subcommand sets up the following AWS infrastructure resources:
+ Option of configuring pipeline permissions through:
  + A pipeline IAM user with access key ID and secret key access credentials to be shared with the CI/CD system.
**Note**  
We recommend rotating access keys regularly. For more information, see [ Rotate access keys regularly for use cases that require long-term credentials ](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#rotate-credentials) in the *IAM User Guide*.
  + Supported CI/CD platforms through OIDC. For an introduction on using OIDC with AWS SAM pipeline, go to [How to use OIDC authentication with AWS SAM pipelines](deploying-with-oidc.md).
+ An CloudFormation execution IAM role assumed by CloudFormation to deploy the AWS SAM application.
+ An Amazon S3 bucket to hold the AWS SAM artifacts.
+ Optionally, an Amazon ECR image repository to hold container image Lambda deployment packages (if you have a resource that is of package type `Image`).

## Usage
<a name="sam-cli-command-reference-sam-pipeline-bootstrap-usage"></a>

```
$ sam pipeline bootstrap <options>
```

## Options
<a name="sam-cli-command-reference-sam-pipeline-bootstrap-options"></a>

`--bitbucket-repo-uuid TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-bitbucket-repo-uuid"></a>
 The UUID of the Bitbucket repository. This option is specific to using Bitbucket OIDC for permissions.  
This value can be found at https://bitbucket.org/*workspace*/*repository*/admin/addon/admin/pipelines/openid-connect 

`--bucket TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-bucket"></a>
The ARN of the Amazon S3 bucket that holds the AWS SAM artifacts.

`--cicd-provider TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-cicd-provider"></a>
The CI/CD platform for the AWS SAM pipeline.

`--cloudformation-execution-role TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-cloudformation-execution-role"></a>
The ARN of the IAM role to be assumed by CloudFormation while deploying the application's stack. Provide only if you want to use your own role. Otherwise, the command will create a new role.

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-config-env"></a>
The environment name that specifies the default parameter values in the configuration file to use. The default value is **default**. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-config-file"></a>
The path and file name of the configuration file containing the default parameter values to use. The default value is `samconfig.toml` in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--confirm-changeset | --no-confirm-changeset`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-confirm-changeset"></a>
Prompt to confirm the deployment of your resources.

`--create-image-repository | --no-create-image-repository`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-create-image-repository"></a>
Specify whether to create an Amazon ECR image repository if none is provided. The Amazon ECR repository holds the container images of Lambda functions, or layers having a package type of `Image`. The default is `--no-create-image-repository`.

`--debug`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-debug"></a>
Turns on debug logging and prints debug messages that the AWS SAM CLI generates, and to display timestamps.

`--deployment-branch TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-deployment-branch"></a>
Name of the branch that deployments will occur from. This option is specific to using GitHub Actions OIDC for permissions.

`--github-org TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-github-org"></a>
The GitHub organization that the repository belongs to. If no organization exists, enter the user name of the repository owner. This option is specific to using GitHub Actions OIDC for permissions.

`--github-repo TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-github-repo"></a>
Name of the GitHub repository that deployments will occur from. This option is specific to using GitHub Actions OIDC for permissions.

`--gitlab-group TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-gitlab-group"></a>
The GitLab group that the repository belongs to. This option is specific to using GitLab OIDC for permissions.

`--gitlab-project TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-gitlab-project"></a>
The GitLab project name. This option is specific to using GitLab OIDC for permissions.

`--help, -h`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-help"></a>
Shows this message and exits.

`--image-repository TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-image-repository"></a>
The ARN of an Amazon ECR image repository that holds the container images of Lambda functions, or layers that have a package type of `Image`. If provided, the `--create-image-repository` options is ignored. If not provided and `--create-image-repository` is specified, the command creates one.

`--interactive | --no-interactive`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-interactive"></a>
Disable interactive prompting for bootstrap parameters and fail if any required parameters are missing. The default value is `--interactive`. For this command, `--stage` is the only required parameter.  
If `--no-interactive` is specified along with `--use-oidc-provider`, all required parameters for your OIDC provider must be included.

`--oidc-client-id TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-oidc-client-id"></a>
The client ID configured for use with your OIDC provider.

`--oidc-provider [github-actions | gitlab | bitbucket-pipelines]`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-oidc-provider"></a>
Name of the CI/CD provider that will be used for OIDC permissions. GitLab, GitHub, and Bitbucket are supported.

`--oidc-provider-url TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-oidc-provider-url"></a>
The URL for the OIDC provider. Value must begin with **https://**.

`--permissions-provider [oidc | iam]`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-permissions-provider"></a>
Choose a permissions provider to assume the pipeline execution role. The default value is **iam**.

`--pipeline-execution-role TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-pipeline-execution-role"></a>
The ARN of the IAM role to be assumed by the pipeline user to operate on this stage. Provide only if you want to use your own role. If not provided, this command will create a new role.

`--pipeline-user TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-pipeline-user"></a>
The Amazon Resource Name (ARN) of the IAM user having its access key ID and secret access key shared with the CI/CD system. It is used to grant this IAM user permission to access the corresponding AWS account. If not provided, the command will create an IAM user along with the access key ID and secret access key credentials.

`--profile TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-region"></a>
The AWS Region to deploy to. For example, `us-east-1`.

`--save-params`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--stage TEXT`  <a name="sam-cli-command-reference-sam-pipeline-bootstrap-options-stage"></a>
The name of the corresponding deployment stage. It is used as a suffix for the created AWS infrastructure resources.

## Troubleshooting
<a name="sam-cli-command-reference-sam-pipeline-bootstrap-troubleshooting"></a>

### Error: Missing required parameter
<a name="sam-cli-command-reference-sam-pipeline-bootstrap-troubleshooting-example1"></a>

When `--no-interactive` is specified along with `--use-oidc-provider` and any of the required parameters are not provided, this error message will be displayed along with a description of the missing parameters.

## Example
<a name="sam-cli-command-reference-sam-pipeline-bootstrap-examples"></a>

The following example creates the AWS resources required to create your CI/CD system, and it turns on debug logging and prints debug messages generated by the AWS SAM CLI: uses a generated event for local testing by using an `s3.json` event to invoke a Lambda function locally

```
$ sam pipeline bootstrap --debug
```

# sam pipeline init
<a name="sam-cli-command-reference-sam-pipeline-init"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam pipeline init` subcommand.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam pipeline init` subcommand generates a pipeline configuration file that your CI/CD system can use to deploy serverless applications using AWS SAM.

Before using **sam pipeline init**, you must bootstrap the necessary resources for each stage in your pipeline. You can do this by running **sam pipeline init --bootstrap** to be guided through the setup and configuration file generation process, or refer to resources you have previously created with the **sam pipeline bootstrap** command.

## Usage
<a name="sam-cli-command-reference-sam-pipeline-init-usage"></a>

```
$ sam pipeline init <options>
```

## Options
<a name="sam-cli-command-reference-sam-pipeline-init-options"></a>

`--bootstrap`  <a name="sam-cli-command-reference-sam-pipeline-init-options-bootstrap"></a>
Enable interactive mode that walks the user through creating necessary AWS infrastructure resources.

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-pipeline-init-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is `default`. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file TEXT`  <a name="sam-cli-command-reference-sam-pipeline-init-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is `samconfig.toml` in the project root directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--debug`  <a name="sam-cli-command-reference-sam-pipeline-init-options-debug"></a>
Turns on debug logging to print debug messages that the AWS SAM CLI generates, and to display timestamps.

`--help, -h`  <a name="sam-cli-command-reference-sam-pipeline-init-options-help"></a>
Shows this message and exits.

`--save-params`  <a name="sam-cli-command-reference-sam-pipeline-init-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

## Example
<a name="sam-cli-command-reference-sam-pipeline-init-examples"></a>

The following example shows you how to use the `--bootstrap` option to allow you to walkthrough an interactive mode that walks you through creating necessary AWS infrastructure resources:

```
$ sam pipeline init --bootstrap
```

# sam publish
<a name="sam-cli-command-reference-sam-publish"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam publish` command.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam publish` command publishes an AWS SAM application to the AWS Serverless Application Repository. This command takes a packaged AWS SAM template and publishes the application to the specified AWS Region.

The `sam publish` command expects the AWS SAM template to include a `Metadata` section that contains application metadata required for publishing. In the `Metadata` section, the `LicenseUrl` and `ReadmeUrl` properties must refer to Amazon Simple Storage Service (Amazon S3) buckets, not local files. For more information about the `Metadata` section of the AWS SAM template, see [Publishing your application with the AWS SAM CLI](serverless-sam-template-publishing-applications.md).

By default, `sam publish` creates the application as private. Before other AWS accounts are allowed to view and deploy your application, you must share it. For information on sharing applications, see [AWS Serverless Application Repository Resource-Based Policy Examples](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/security_iam_resource-based-policy-examples.html) in the *AWS Serverless Application Repository Developer Guide*.

**Note**  
Currently `sam publish` doesn't support publishing nested applications that are specified locally. If your application contains nested applications, you must publish them separately to the AWS Serverless Application Repository before publishing your parent application.

## Usage
<a name="sam-cli-command-reference-sam-publish-usage"></a>

```
$ sam publish <options>
```

## Options
<a name="sam-cli-command-reference-sam-publish-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-publish-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-sam-publish-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "`samconfig.toml`" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--debug`  <a name="sam-cli-command-reference-sam-publish-options-debug"></a>
Turns on debug logging to print debug messages that the AWS SAM CLI generates, and to display timestamps.

`--help`  <a name="sam-cli-command-reference-sam-publish-options-help"></a>
Shows this message and exits.

`--profile TEXT`  <a name="sam-cli-command-reference-sam-publish-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="sam-cli-command-reference-sam-publish-options-region"></a>
The AWS Region to deploy to. For example, us-east-1.

`--save-params`  <a name="sam-cli-command-reference-sam-publish-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--semantic-version TEXT`  <a name="sam-cli-command-reference-sam-publish-options-semantic-version"></a>
(Optional) Use this option to provide a semantic version of your application that overrides the `SemanticVersion` property in the `Metadata` section of the template file. For more information about semantic versioning, see the [Semantic Versioning specification](https://semver.org/).

`--template, -t PATH`  <a name="sam-cli-command-reference-sam-publish-options-template"></a>
The path of AWS SAM template file `[default: template.[yaml|yml]]`.

## Examples
<a name="sam-cli-command-reference-sam-publish-examples"></a>

To publish an application:

```
$ sam publish --template packaged.yaml --region us-east-1
```

# sam remote callback
<a name="sam-cli-command-reference-sam-remote-callback"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam remote callback` command.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam remote callback` command allows you to send callbacks to remote durable function executions running in AWS Lambda.

**Note**  
These commands require access to AWS credentials.

## Usage
<a name="sam-cli-command-reference-sam-remote-callback-usage"></a>

```
$ sam remote callback <subcommand> <options>
```

## Options
<a name="sam-cli-command-reference-sam-remote-callback-options"></a>

`--help, -h`  <a name="sam-cli-command-reference-sam-remote-callback-options-help"></a>
Show this message and exit.

## Subcommands
<a name="sam-cli-command-reference-sam-remote-callback-subcommands"></a>

`succeed`  <a name="sam-cli-command-reference-sam-remote-callback-subcommands-succeed"></a>
Send a callback success to a remote durable function execution. For more information, see [sam remote callback succeed](sam-cli-command-reference-sam-remote-callback-succeed.md).

`fail`  <a name="sam-cli-command-reference-sam-remote-callback-subcommands-fail"></a>
Send a callback failure to a remote durable function execution. For more information, see [sam remote callback fail](sam-cli-command-reference-sam-remote-callback-fail.md).

`heartbeat`  <a name="sam-cli-command-reference-sam-remote-callback-subcommands-heartbeat"></a>
Send a callback heartbeat to a remote durable function execution. For more information, see [sam remote callback heartbeat](sam-cli-command-reference-sam-remote-callback-heartbeat.md).

# sam remote callback succeed
<a name="sam-cli-command-reference-sam-remote-callback-succeed"></a>

Send a callback success to a remote durable function execution.

**Note**  
This command requires access to AWS credentials.

## Usage
<a name="ref-sam-cli-remote-callback-succeed-usage"></a>

```
$ sam remote callback succeed CALLBACK_ID [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-remote-callback-succeed-arguments"></a>

`CALLBACK_ID`  
The unique identifier of the callback to send a success response to.

## Options
<a name="ref-sam-cli-remote-callback-succeed-options"></a>

`-r, --result TEXT`  
Success result payload as string.

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-remote-callback-succeed-examples"></a>

Send success callback with no result:

```
$ sam remote callback succeed my-callback-id
```

Send success callback with result:

```
$ sam remote callback succeed my-callback-id --result 'Task completed successfully'
```

# sam remote callback fail
<a name="sam-cli-command-reference-sam-remote-callback-fail"></a>

Send a callback failure to a remote durable function execution.

**Note**  
This command requires access to AWS credentials.

## Usage
<a name="ref-sam-cli-remote-callback-fail-usage"></a>

```
$ sam remote callback fail CALLBACK_ID [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-remote-callback-fail-arguments"></a>

`CALLBACK_ID`  
The unique identifier of the callback to send a failure response to.

## Options
<a name="ref-sam-cli-remote-callback-fail-options"></a>

`--error-data TEXT`  
Additional error data.

`--stack-trace TEXT`  
Stack trace entries. This option can be specified multiple times.

`--error-type TEXT`  
Type of error.

`--error-message TEXT`  
Detailed error message.

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-remote-callback-fail-examples"></a>

Send failure callback with no parameters:

```
$ sam remote callback fail my-callback-id
```

Send failure callback with error message:

```
$ sam remote callback fail my-callback-id --error-message 'Task failed'
```

Send failure callback with all parameters:

```
$ sam remote callback fail my-callback-id --error-message 'Task failed' --error-type 'ValidationError' --stack-trace 'at line 42' --error-data '{"code": 500}'
```

# sam remote callback heartbeat
<a name="sam-cli-command-reference-sam-remote-callback-heartbeat"></a>

Send a callback heartbeat to a remote durable function execution.

**Note**  
This command requires access to AWS credentials.

## Usage
<a name="ref-sam-cli-remote-callback-heartbeat-usage"></a>

```
$ sam remote callback heartbeat CALLBACK_ID [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-remote-callback-heartbeat-arguments"></a>

`CALLBACK_ID`  
The unique identifier of the callback to send a heartbeat to.

## Options
<a name="ref-sam-cli-remote-callback-heartbeat-options"></a>

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-remote-callback-heartbeat-examples"></a>

Send heartbeat callback:

```
$ sam remote callback heartbeat my-callback-id
```

# sam remote execution
<a name="sam-cli-command-reference-sam-remote-execution"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam remote execution` command.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam remote execution` command allows you to manage and inspect remote durable function executions running in AWS Lambda.

**Note**  
These commands require access to AWS credentials.

## Usage
<a name="sam-cli-command-reference-sam-remote-execution-usage"></a>

```
$ sam remote execution <subcommand> <options>
```

## Options
<a name="sam-cli-command-reference-sam-remote-execution-options"></a>

`--help, -h`  <a name="sam-cli-command-reference-sam-remote-execution-options-help"></a>
Show this message and exit.

## Subcommands
<a name="sam-cli-command-reference-sam-remote-execution-subcommands"></a>

`get`  <a name="sam-cli-command-reference-sam-remote-execution-subcommands-get"></a>
Get details of a durable execution. For more information, see [sam remote execution get](sam-cli-command-reference-sam-remote-execution-get.md).

`history`  <a name="sam-cli-command-reference-sam-remote-execution-subcommands-history"></a>
Get execution history of a durable function execution. For more information, see [sam remote execution history](sam-cli-command-reference-sam-remote-execution-history.md).

`stop`  <a name="sam-cli-command-reference-sam-remote-execution-subcommands-stop"></a>
Stop a durable function execution. For more information, see [sam remote execution stop](sam-cli-command-reference-sam-remote-execution-stop.md).

# sam remote execution get
<a name="sam-cli-command-reference-sam-remote-execution-get"></a>

Retrieve the details of a specific durable function execution from AWS Lambda.

The execution ARN should be in the format returned by Invoke or found in execution logs.

**Note**  
This command requires access to AWS credentials.

## Usage
<a name="ref-sam-cli-remote-execution-get-usage"></a>

```
$ sam remote execution get DURABLE_EXECUTION_ARN [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-remote-execution-get-arguments"></a>

`DURABLE_EXECUTION_ARN`  
The Amazon Resource Name (ARN) of the durable function execution to retrieve details for.

## Options
<a name="ref-sam-cli-remote-execution-get-options"></a>

`--format [summary|json]`  
Output format. Default: `summary`

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-remote-execution-get-examples"></a>

Get execution details with default summary format:

```
$ sam remote execution get 'arn:aws:lambda:us-east-1:123456789012:function:my-function:$LATEST/durable-execution/c63eec67-3415-4eb4-a495-116aa3a86278/1d454231-a3ad-3694-aa03-c917c175db55'
```

Get execution details in JSON format:

```
$ sam remote execution get 'arn:aws:lambda:us-east-1:123456789012:function:my-function:$LATEST/durable-execution/c63eec67-3415-4eb4-a495-116aa3a86278/1d454231-a3ad-3694-aa03-c917c175db55' --format json
```

**Note**  
You must ensure that control characters in the execution ARN like `$` are escaped properly when using shell commands.

# sam remote execution history
<a name="sam-cli-command-reference-sam-remote-execution-history"></a>

Retrieve the execution history of a specific durable function execution from AWS Lambda.

The execution ARN should be in the format returned by StartDurableExecution or found in execution logs.

**Note**  
This command requires access to AWS credentials.

## Usage
<a name="ref-sam-cli-remote-execution-history-usage"></a>

```
$ sam remote execution history DURABLE_EXECUTION_ARN [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-remote-execution-history-arguments"></a>

`DURABLE_EXECUTION_ARN`  
The Amazon Resource Name (ARN) of the durable function execution to retrieve history for.

## Options
<a name="ref-sam-cli-remote-execution-history-options"></a>

`--format [table|json]`  
Output format. Default: `table`

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-remote-execution-history-examples"></a>

Get execution history with default table format:

```
$ sam remote execution history arn:aws:lambda:us-east-1:123456789012:function:MyFunction:$LATEST/durable-execution/my-execution-name/my-execution-id
```

Get execution history in JSON format:

```
$ sam remote execution history arn:aws:lambda:us-east-1:123456789012:function:MyFunction:$LATEST/durable-execution/my-execution-name/my-execution-id --format json
```

# sam remote execution stop
<a name="sam-cli-command-reference-sam-remote-execution-stop"></a>

Stop a running durable function execution in AWS Lambda.

The execution ARN should be in the format returned by StartDurableExecution or found in execution logs.

**Note**  
This command requires access to AWS credentials.

## Usage
<a name="ref-sam-cli-remote-execution-stop-usage"></a>

```
$ sam remote execution stop DURABLE_EXECUTION_ARN [OPTIONS]
```

## Required Arguments
<a name="ref-sam-cli-remote-execution-stop-arguments"></a>

`DURABLE_EXECUTION_ARN`  
The Amazon Resource Name (ARN) of the durable function execution to stop.

## Options
<a name="ref-sam-cli-remote-execution-stop-options"></a>

`--error-message TEXT`  
Error message to associate with the stopped execution.

`--error-type TEXT`  
Error type to associate with the stopped execution.

`--error-data TEXT`  
Error data to associate with the stopped execution.

`--stack-trace TEXT`  
Stack trace entries. This option can be specified multiple times.

`--region TEXT`  
Set the AWS Region of the service (for example, `us-east-1`).

`--profile TEXT`  
Select a specific profile from your credential file to get AWS credentials.

`--config-env TEXT`  
Environment name specifying default parameter values in the configuration file. Default: `default`

`--config-file TEXT`  
Configuration file containing default parameter values. Default: `samconfig.toml`

`--save-params`  
Save the parameters provided via the command line to the configuration file.

`--beta-features / --no-beta-features`  
Enable/Disable beta features.

`--debug`  
Turn on debug logging to print debug messages generated by AWS SAM CLI and display timestamps.

`-h, --help`  
Shows this message and exits.

## Examples
<a name="ref-sam-cli-remote-execution-stop-examples"></a>

Stop execution without error details:

```
$ sam remote execution stop arn:aws:lambda:us-east-1:123456789012:function:MyFunction:$LATEST/durable-execution/my-execution-name/my-execution-id
```

Stop execution with error message and type:

```
$ sam remote execution stop arn:aws:lambda:us-east-1:123456789012:function:MyFunction:$LATEST/durable-execution/my-execution-name/my-execution-id --error-message "Execution cancelled" --error-type "UserCancellation"
```

Stop execution with full error details and stack trace:

```
$ sam remote execution stop arn:aws:lambda:us-east-1:123456789012:function:MyFunction:$LATEST/durable-execution/my-execution-name/my-execution-id --error-message "Task failed" --error-type "TaskFailure" --error-data '{"reason":"timeout"}' --stack-trace "at function1()" --stack-trace "at function2()"
```

# sam remote invoke
<a name="sam-cli-command-reference-remote-invoke"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam remote invoke` command.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam remote invoke` command, see [Introduction to testing in the cloud with sam remote invoke](using-sam-cli-remote-invoke.md).

The `sam remote invoke` command invokes supported resources in the AWS Cloud.

## Usage
<a name="sam-cli-command-reference-remote-invoke-usage"></a>

```
$ sam remote invoke <arguments> <options>
```

## Arguments
<a name="sam-cli-command-reference-remote-invoke-args"></a>

**Resource ID**  <a name="sam-cli-command-reference-remote-invoke-args-resource-id"></a>
The ID of the suppored resource to invoke.  
This argument accepts the following values:  
+ **Amazon Resource Name (ARN)** – The ARN of the resource.
**Tip**  
Use `sam list stack-outputs --stack-name <stack-name>` to obtain the ARN of your resources.
+ **Logical ID** – The logical ID of the resource. You must also provide the AWS CloudFormation stack name using the `--stack-name` option.
+ **Physical ID** – The physical ID of the resource. This ID gets created when you deploy a resource using CloudFormation.
**Tip**  
Use `sam list resources --stack-name <stack-name>` to obtain the physical ID of your resources.  
**When you provide an ARN or physical ID:**  
If you provide an ARN or physical ID, do not provide a stack name. When the stack name is provided using the `--stack-name` option, or when the stack name is defined in your configuration file, the AWS SAM CLI will automatically process your resource ID as a logical ID value from the CloudFormation stack.  
**When you don't provide a resource ID:**  
If you don't provide a resource ID, but do provide a stack name with the `--stack-name` option, the AWS SAM CLI will attempt to automatically invoke a resource in your CloudFormation stack using the following logic:  

1. The AWS SAM CLI will identify resource types in the following order and move to the next step once the resource type is found in your stack:

   1. Lambda

   1. Step Functions

   1. Amazon SQS

   1. Kinesis Data Streams

1. If the resource type has a single resource in your stack, the AWS SAM CLI will invoke it. If multiple resources of the resource type exists in your stack, the AWS SAM CLI will return an error.
The following are examples of what the AWS SAM CLI will do:  
+ **Stack that contains two Lambda functions and an Amazon SQS queue** – The AWS SAM CLI will locate the Lambda resource type and return and error since the stack contains more than one Lambda function.
+ **Stack that contains a Lambda function and two Amazon Kinesis Data Streams applications** – The AWS SAM CLI will locate the Lambda function and invoke it since the stack contains a single Lambda resource.
+ **Stack that contains a single Amazon SQS queue and two Kinesis Data Streams applications** – The AWS SAM CLI will locate the Amazon SQS queue and invoke it since the stack contains a single Amazon SQS queue.

## Options
<a name="sam-cli-command-reference-remote-invoke-options"></a>

`--beta-features | --no-beta-features`  <a name="sam-cli-command-reference-remote-invoke-options-beta-features"></a>
Allow or deny beta features.

`--config-env TEXT`  <a name="sam-cli-command-reference-remote-invoke-options-config-env"></a>
Specify the environment to use from your AWS SAM CLI configuration file.  
*Default*: `default`

`--config-file FILENAME`  <a name="sam-cli-command-reference-remote-invoke-options-config-file"></a>
Specify the path and file name of your configuration file.  
For more information about configuration files, see [Configuring the AWS SAM CLI](using-sam-cli-configure.md).  
*Default*: `samconfig.toml` at the root of your project directory. 

`--debug`  <a name="sam-cli-command-reference-remote-invoke-options-debug"></a>
Activate debug logging. This prints debug messages and timestamps generated by the AWS SAM CLI.

`--event, -e TEXT`  <a name="sam-cli-command-reference-remote-invoke-options-event"></a>
The event to send to the target resource.

`--event-file FILENAME`  <a name="sam-cli-command-reference-remote-invoke-options-event-file"></a>
The path to a file that contains the event to send to the target resource.

`--help, -h`  <a name="sam-cli-command-reference-remote-invoke-options-help"></a>
Show the help message and exit.

`--output [ text | json ]`  <a name="sam-cli-command-reference-remote-invoke-options-output"></a>
Output the results of your invocation in a specific output format.  
`json` – The request metadata and resource response are returned in JSON structure. The response contains the full SDK output.  
`text` – The request metadata is returned in text structure. The resource response is returned in the output format of the invoked resource.

`--parameter`  <a name="sam-cli-command-reference-remote-invoke-options-parameter"></a>
Additional [https://boto3.amazonaws.com/v1/documentation/api/latest/index.html](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) parameters that you can pass to the resource being invoked.    
**Amazon Kinesis Data Streams**  <a name="sam-cli-command-reference-remote-invoke-options-parameter-kinesis"></a>
The following additional parameters can be used to put a record in the Kinesis data stream:  
+ `ExplicitHashKey='string'`
+ `PartitionKey='string'`
+ `SequenceNumberForOrdering='string'`
+ `StreamARN='string'`
For a description of each parameter, see [Kinesis.Client.put\$1record](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/kinesis/client/put_record.html).  
**AWS Lambda**  <a name="sam-cli-command-reference-remote-invoke-options-parameter-lambda"></a>
The following additional parameters can be used to invoke a Lambda resource and receive a buffered response:  
+ `ClientContext='base64-encoded string'`
+ `InvocationType='[ DryRun | Event | RequestResponse ]'`
+ `LogType='[ None | Tail ]'`
+ `Qualifier='string'`
The following additional parameters can be used to invoke a Lambda resource with response streaming:  
+ `ClientContext='base64-encoded string'`
+ `InvocationType='[ DryRun | RequestResponse ]'`
+ `LogType='[ None | Tail ]'`
+ `Qualifier='string'`
For a description of each parameter, see the following:  
+ Lambda with buffered response – [Lambda.Client.invoke](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lambda/client/invoke.html)
+ Lambda with response streaming – [Lambda.Client.invoke\$1with\$1response\$1stream](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lambda/client/invoke_with_response_stream.html)  
**Amazon Simple Queue Service (Amazon SQS)**  <a name="sam-cli-command-reference-remote-invoke-options-parameter-sqs"></a>
The following additional parameters can be used to send a message to an Amazon SQS queue:  
+ `DelaySeconds=integer`
+ `MessageAttributes='json string'`
+ `MessageDeduplicationId='string'`
+ `MessageGroupId='string'`
+ `MessageSystemAttributes='json string'`
For a description of each parameter, see [SQS.Client.send\$1message](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sqs/client/send_message.html).  
**AWS Step Functions**  <a name="sam-cli-command-reference-remote-invoke-options-parameter-sf"></a>
The following additional parameters can be used to start a state machine execution:  
+ `name='string'`
+ `traceHeader='string'`
For a description of each parameter, see [SFN.Client.start\$1execution](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/start_execution.html).

`--profile TEXT`  <a name="sam-cli-command-reference-remote-invoke-options-profile"></a>
The specific profile from your credential file to get AWS credentials.

`--region TEXT`  <a name="sam-cli-command-reference-remote-invoke-options-region"></a>
The AWS Region of the resource. For example, `us-east-1`.

`--stack-name TEXT`  <a name="sam-cli-command-reference-remote-invoke-options-stack-name"></a>
The name of the CloudFormation stack that the resource belongs to.

`--tenant-id TEXT`  <a name="ref-sam-cli-local-invoke-options-tenancyconfig"></a>
The tenant ID for multi-tenant Lambda functions. Used to ensure compute isolation between different tenants. Required when invoking functions configured with tenant isolation mode.

`--test-event-name NAME`  <a name="sam-cli-command-reference-remote-invoke-options-test-event-name"></a>
The name of the shareable test event to pass to your Lambda function.  
This option only supports Lambda functions.

## Example
<a name="sam-cli-command-reference-remote-invoke-examples"></a>

The following example invokes supported resources in the AWS Cloud and activates debug logging, which prints debug messages and timestamps generated by the AWS SAM CLI:

```
$ sam remote invoke--debug
```

# sam remote test-event
<a name="sam-cli-command-reference-remote-test-event"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam remote test-event` command.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam remote test-event` command, see [Introduction to cloud testing with sam remote test-event](using-sam-cli-remote-test-event.md).

The `sam remote test-event` command interacts with shareable test events in the Amazon EventBridge schema registry.

## Usage
<a name="sam-cli-command-reference-remote-test-event-usage"></a>

```
$ sam remote test-event <options> <subcommand>
```

## Options
<a name="sam-cli-command-reference-remote-test-event-options"></a>

`--help, -h`  <a name="sam-cli-command-reference-remote-invoke-options-help"></a>
Show the help message and exit.

## Subcommands
<a name="sam-cli-command-reference-remote-test-event-subcommands"></a>

`delete`  
Delete a shareable test event from the EventBridge schema registry. For more reference information, see [sam remote test-event delete](sam-cli-command-reference-remote-test-event-delete.md).

`get`  
Get a shareable test event from the EventBridge schema registry. For more reference information, see [sam remote test-event get](sam-cli-command-reference-remote-test-event-get.md).

`list`  
List existing shareable test events for an AWS Lambda function. For more reference information, see [sam remote test-event list](sam-cli-command-reference-remote-test-event-list.md).

`put`  
Save an event from a local file to the EventBridge schema registry. For more reference information, see [sam remote test-event put](sam-cli-command-reference-remote-test-event-put.md).

# sam remote test-event delete
<a name="sam-cli-command-reference-remote-test-event-delete"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam remote test-event delete` subcommand.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam remote test-event` command, see [Introduction to cloud testing with sam remote test-event](using-sam-cli-remote-test-event.md).

The `sam remote test-event delete` subcommand deletes a shareable test event from the Amazon EventBridge schema registry.

## Usage
<a name="sam-cli-command-reference-remote-test-event-delete-usage"></a>

```
$ sam remote test-event delete <arguments> <options>
```

## Arguments
<a name="sam-cli-command-reference-remote-test-event-delete-args"></a>

**Resource ID**  <a name="sam-cli-command-reference-remote-test-event-delete-args-resource-id"></a>
The ID of the AWS Lambda function associated with the shareable test event.  
If you provide a logical ID, you must also provide a value for the AWS CloudFormation stack associated with the Lambda function using the `--stack-name` option.  
*Valid values*: The resource's logical ID or resource ARN.

## Options
<a name="sam-cli-command-reference-remote-test-event-delete-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-remote-test-event-delete-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-remote-test-event-delete-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "`samconfig.toml`" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--help, -h`  <a name="sam-cli-command-reference-remote-test-event-delete-options-help"></a>
Show the help message and exit.

`--name TEXT`  <a name="sam-cli-command-reference-remote-test-event-delete-options-name"></a>
The name of the shareable test event to delete.

`--stack-name TEXT`  <a name="sam-cli-command-reference-remote-test-event-delete-options-stack-name"></a>
The name of the CloudFormation stack associated with the Lambda function.  
This option is required if you are providing the Lambda function logical ID as an argument.

# sam remote test-event get
<a name="sam-cli-command-reference-remote-test-event-get"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam remote test-event get` subcommand.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam remote test-event` command, see [Introduction to cloud testing with sam remote test-event](using-sam-cli-remote-test-event.md).

The `sam remote test-event get` subcommand gets a shareable test event from the Amazon EventBridge schema registry.

## Usage
<a name="sam-cli-command-reference-remote-test-event-get-usage"></a>

```
$ sam remote test-event get <arguments> <options>
```

## Arguments
<a name="sam-cli-command-reference-remote-test-event-get-args"></a>

**Resource ID**  <a name="sam-cli-command-reference-remote-test-event-get-args-resource-id"></a>
The ID of the AWS Lambda function associated with the shareable test event to get.  
If you provide a logical ID, you must also provide a value for the AWS CloudFormation stack associated with the Lambda function using the `--stack-name` option.  
*Valid values*: The resource's logical ID or resource ARN.

## Options
<a name="sam-cli-command-reference-remote-test-event-get-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-remote-test-event-get-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-remote-test-event-get-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "`samconfig.toml`" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--help, -h`  <a name="sam-cli-command-reference-remote-test-event-get-options-help"></a>
Show the help message and exit.

`--name TEXT`  <a name="sam-cli-command-reference-remote-test-event-get-options-name"></a>
The name of the shareable test event to get.

`--output-file FILENAME`  <a name="sam-cli-command-reference-remote-test-event-get-options-output-file"></a>
The file path and name to save the event to on your local machine.  
If you don’t provide this option, the AWS SAM CLI will output the contents of the shareable test event to your console.

`--stack-name TEXT`  <a name="sam-cli-command-reference-remote-test-event-get-options-stack-name"></a>
The name of the CloudFormation stack associated with the Lambda function.  
This option is required if you are providing the Lambda function logical ID as an argument.

# sam remote test-event list
<a name="sam-cli-command-reference-remote-test-event-list"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam remote test-event list` subcommand.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam remote test-event` command, see [Introduction to cloud testing with sam remote test-event](using-sam-cli-remote-test-event.md).

The `sam remote test-event list` subcommand lists the existing shareable test events for a specific AWS Lambda function from the Amazon EventBridge schema registry.

## Usage
<a name="sam-cli-command-reference-remote-test-event-list-usage"></a>

```
$ sam remote test-event list <arguments> <options>
```

## Arguments
<a name="sam-cli-command-reference-remote-test-event-list-args"></a>

**Resource ID**  <a name="sam-cli-command-reference-remote-test-event-list-args-resource-id"></a>
The ID of the Lambda function associated with the shareable test events.  
If you provide a logical ID, you must also provide a value for the AWS CloudFormation stack associated with the Lambda function using the `--stack-name` option.  
*Valid values*: The resource's logical ID or resource ARN.

## Options
<a name="sam-cli-command-reference-remote-test-event-list-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-remote-test-event-list-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-remote-test-event-list-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "`samconfig.toml`" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--help, -h`  <a name="sam-cli-command-reference-remote-test-event-list-options-help"></a>
Show the help message and exit.

`--stack-name TEXT`  <a name="sam-cli-command-reference-remote-test-event-list-options-stack-name"></a>
The name of the CloudFormation stack associated with the Lambda function.  
This option is required if you are providing the Lambda function logical ID as an argument.

## Examples
<a name="sam-cli-command-reference-remote-test-event-list-examples"></a>

For examples on using this command, refer to [Listing shareable test events](using-sam-cli-remote-test-event.md#using-sam-cli-remote-test-event-use-list).

# sam remote test-event put
<a name="sam-cli-command-reference-remote-test-event-put"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam remote test-event put` subcommand.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI `sam remote test-event` command, see [Introduction to cloud testing with sam remote test-event](using-sam-cli-remote-test-event.md).

The `sam remote test-event put` subcommand saves a shareable test event from your local machine to the Amazon EventBridge schema registry.

## Usage
<a name="sam-cli-command-reference-remote-test-event-put-usage"></a>

```
$ sam remote test-event put <arguments> <options>
```

## Arguments
<a name="sam-cli-command-reference-remote-test-event-put-args"></a>

**Resource ID**  <a name="sam-cli-command-reference-remote-test-event-put-args-resource-id"></a>
The ID of the AWS Lambda function associated with the shareable test event.  
If you provide a logical ID, you must also provide a value for the AWS CloudFormation stack associated with the Lambda function using the `--stack-name` option.  
*Valid values*: The resource's logical ID or resource ARN.

## Options
<a name="sam-cli-command-reference-remote-test-event-put-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-remote-test-event-put-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-remote-test-event-put-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "`samconfig.toml`" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--file FILENAME`  <a name="sam-cli-command-reference-remote-test-event-put-options-file"></a>
The file path and name to the event to on your local machine.  
Provide `-` as the file name value to read from `stdin`.  
This option is required.

`--force`, `-f`  <a name="sam-cli-command-reference-remote-test-event-put-options-force"></a>
Overwrite a shareable test event with the same name.

`--help, -h`  <a name="sam-cli-command-reference-remote-test-event-put-options-help"></a>
Show the help message and exit.

`--name TEXT`  <a name="sam-cli-command-reference-remote-test-event-put-options-name"></a>
The name to save the shareable test event as.  
If a shareable test event with the same name exists in the EventBridge schema registry, the AWS SAM CLI will not overwrite it. To overwrite, add the `--force` option.

`--output-file FILENAME`  <a name="sam-cli-command-reference-remote-test-event-put-options-output-file"></a>
The file path and name to save the event to on your local machine.  
If you don’t provide this option, the AWS SAM CLI will output the contents of the shareable test event to your console.

`--stack-name TEXT`  <a name="sam-cli-command-reference-remote-test-event-put-options-stack-name"></a>
The name of the CloudFormation stack associated with the Lambda function.  
This option is required if you are providing the Lambda function logical ID as an argument.

## Example
<a name="sam-cli-command-reference-remote-test-event-put-examples"></a>

For an example on using this command, refer to [Saving shareable test events](using-sam-cli-remote-test-event.md#using-sam-cli-remote-test-event-use-put).

# sam sync
<a name="sam-cli-command-reference-sam-sync"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam sync` command.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the AWS SAM CLI, see [AWS SAM CLI](using-sam-cli.md).

The `sam sync` command syncs local application changes to the AWS Cloud.

## Usage
<a name="sam-cli-command-reference-sam-sync-usage"></a>

```
$ sam sync <options>
```

## Options
<a name="sam-cli-command-reference-sam-sync-options"></a>

`--base-dir, -s DIRECTORY`  <a name="sam-cli-command-reference-sam-sync-options-base-dir"></a>
Resolves relative paths to the function's or layer's source code with respect to this directory. Use this option to change how relative paths to source code folders are resolved. By default, relative paths are resolved with respect to the AWS SAM template's location.  
In addition to the resources in the root application or stack that you're building, this option also applies to nested applications or stacks. Additionally, this option applies to the following resource types and properties:  
+ Resource type: `AWS::Serverless::Function` Property: `CodeUri`
+ Resource type: `AWS::Serverless::Function` Resource attribute: `Metadata` Entry: `DockerContext`
+ Resource type: `AWS::Serverless::LayerVersion` Property: `ContentUri`
+ Resource type: `AWS::Lambda::Function` Property: `Code`
+ Resource type: `AWS::Lambda::LayerVersion` Property: `Content`

`--build-image TEXT`  <a name="sam-cli-command-reference-sam-sync-options-build-image"></a>
The URI for the [container image](serverless-image-repositories.md#serverless-image-repository-uris) that you want to use when building your application. By default, AWS SAM uses the container image repository URI from [Amazon Elastic Container Registry (Amazon ECR) Public](https://docs.aws.amazon.com/AmazonECR/latest/public/what-is-ecr.html). Specify this option to use a different image.  
You can use this option multiple times in a single command. Each option accepts a string or a key-value pair.  
+ **String** – Specify the URI of the container image that all resources in your application will use. The following is an example:

  ```
  $ sam sync --build-image amazon/aws-sam-cli-build-image-python3.8
  ```
+ **Key-value pair** – Specify the resource name as the key and the container image URI to be used with that resource as the value. Use this format to specify a different container image URI for each resource in your application. The following is an example:

  ```
  $ sam sync --build-image Function1=amazon/aws-sam-cli-build-image-python3.8
  ```
This option only applies if the `--use-container` option is specified, otherwise an error will result.

`--build-in-source | --no-build-in-source`  <a name="sam-cli-command-reference-sam-sync-options-build-in-source"></a>
Provides `--build-in-source` to build your project directly in the source folder.  
The `--build-in-source` option supports the following runtimes and build methods:  
+ **Runtimes** – Any Node.js runtime supported by the `sam init --runtime` option.
+ **Build methods** – `Makefile`, `esbuild`.
The `--build-in-source` option is not compatible with the following options:  
+ `--use-container `
*Default*: `--no-build-in-source`

`--capabilities LIST`  <a name="sam-cli-command-reference-sam-sync-options-capabilities"></a>
A list of capabilities that you specify to allow CloudFormation to create certain stacks. Some stack templates might include resources that can affect permissions in your AWS account. For example, by creating new AWS Identity and Access Management (IAM) users. Specify this option to override the default values. Valid values include the following:  
+ CAPABILITY\$1IAM
+ CAPABILITY\$1NAMED\$1IAM
+ CAPABILITY\$1RESOURCE\$1POLICY
+ CAPABILITY\$1AUTO\$1EXPAND
*Default*: `CAPABILITY_NAMED_IAM` and `CAPABILITY_AUTO_EXPAND`

`--code`  <a name="sam-cli-command-reference-sam-sync-options-code"></a>
By default, AWS SAM syncs all resources in your application. Specify this option to sync only code resources, which include the following:  
+ `AWS::Serverless::Function`
+ `AWS::Lambda::Function`
+ `AWS::Serverless::LayerVersion`
+ `AWS::Lambda::LayerVersion`
+ `AWS::Serverless::Api`
+ `AWS::ApiGateway::RestApi`
+ `AWS::Serverless::HttpApi`
+ `AWS::ApiGatewayV2::Api`
+ `AWS::Serverless::StateMachine`
+ `AWS::StepFunctions::StateMachine`
To sync code resources, AWS SAM uses AWS service APIs directly, instead of deploying through AWS CloudFormation. To update your CloudFormation stack, run **sam sync --watch** or **sam deploy**.

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-sync-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-sam-sync-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "`samconfig.toml`" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--dependency-layer | --no-dependency-layer`  <a name="sam-cli-command-reference-sam-sync-options-dependency-layer"></a>
Specifies whether to separate dependencies of individual functions into another layer to speed up the sync process.  
*Default*: `--dependency-layer`

`--image-repository TEXT`  <a name="sam-cli-command-reference-sam-sync-options-image-repository"></a>
The name of the Amazon Elastic Container Registry (Amazon ECR) repository where this command uploads your function's image. Required for functions declared with the `Image` package type.

`--image-repositories TEXT`  <a name="sam-cli-command-reference-sam-sync-options-image-repositories"></a>
A mapping of functions to their Amazon ECR repository URI. Reference functions by their logical ID. The following is an example:  

```
$ sam sync --image-repositories Function1=123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo
```
You can specify this option multiple times in a single command.

`--kms-key-id TEXT`  <a name="sam-cli-command-reference-sam-sync-options-kms-key-id"></a>
The ID of an AWS Key Management Service (AWS KMS) key used to encrypt artifacts that are at rest in the Amazon S3 bucket. If you don't specify this option, then AWS SAM uses Amazon S3-managed encryption keys.

`--metadata`  <a name="sam-cli-command-reference-sam-sync-options-metadata"></a>
A map of metadata to attach to all artifacts that you reference in your template.

`--notification-arns LIST`  <a name="sam-cli-command-reference-sam-sync-options-notification-arns"></a>
A list of Amazon Simple Notification Service (Amazon SNS) topic ARNs that CloudFormation associates with the stack.

`--no-use-container`  <a name="ref-sam-cli-sync-options-no-use-container"></a>
An option that allows you to use the IDE toolkit to set default behavior.

`--parameter-overrides`  <a name="sam-cli-command-reference-sam-sync-options-parameter-overrides"></a>
A string that contains CloudFormation parameter overrides encoded as key-value pairs. Use the same format as the AWS Command Line Interface (AWS CLI). The AWS SAM CLI format is explicit key and value keywords, each override is separated by a space. Here are two examples:  
+ `--parameter-overrides ParameterKey=hello,ParameterValue=world`
+ `--parameter-overrides ParameterKey=hello,ParameterValue=world ParameterKey=example1,ParameterValue=example2 ParameterKey=apple,ParameterValue=banana`

`--resource TEXT`  <a name="sam-cli-command-reference-sam-sync-options-resource"></a>
Specifies the resource type to sync. To sync multiple resources, you can specify this option multiple times. This option is supported with the `--code` option. The value must be one of the listed resources under `--code`. For example, `--resource AWS::Serverless::Function --resource AWS::Serverless::LayerVersion`.

`--resource-id TEXT`  <a name="sam-cli-command-reference-sam-sync-options-resource-id"></a>
Specifies the resource ID to sync. To sync multiple resources, you can specify this option multiple times. This option is supported with the `--code` option. For example, `--resource-id Function1 --resource-id Function2`.

`--role-arn TEXT`  <a name="sam-cli-command-reference-sam-sync-options-role-arn"></a>
The Amazon Resource Name (ARN) of an IAM role that CloudFormation assumes when applying the changeset.

`--s3-bucket TEXT`  <a name="sam-cli-command-reference-sam-sync-options-s3-bucket"></a>
The name of the Amazon Simple Storage Service (Amazon S3) bucket where this command uploads your CloudFormation template. If your template is larger than 51,200 bytes, then either the `--s3-bucket` or the `--resolve-s3` option is required. If you specify both the `--s3-bucket` and `--resolve-s3` options, then an error occurs.

`--s3-prefix TEXT`  <a name="sam-cli-command-reference-sam-sync-options-s3-prefix"></a>
The prefix added to the names of the artifacts that you upload to the Amazon S3 bucket. The prefix name is a path name (folder name) for the Amazon S3 bucket. This applies only to functions declared with the `Zip` package type.

`--save-params`  <a name="sam-cli-command-reference-sam-sync-options-save-params"></a>
Saves the parameters that you provide at the command line to the AWS SAM configuration file.

`--skip-deploy-sync | --no-skip-deploy-sync`  <a name="sam-cli-command-reference-sam-sync-options-skip-deploy-sync"></a>
Specifies `--skip-deploy-sync` to skip the initial infrastructure sync if it isn't required. The AWS SAM CLI will compare your local AWS SAM template with the deployed CloudFormation template and perform a deployment only if a change is detected.  
Specifies `--no-skip-deploy-sync` to perform an CloudFormation deployment every time `sam sync` is run.  
To learn more, see [Skip the initial CloudFormation deployment](using-sam-cli-sync.md#using-sam-cli-sync-options-skip-deploy-sync).  
*Default*: `--skip-deploy-sync`

`--stack-name TEXT`  <a name="sam-cli-command-reference-sam-sync-options-stack-name"></a>
The name of the CloudFormation stack for your application.  
This option is required.

`--tags LIST`  <a name="sam-cli-command-reference-sam-sync-options-tags"></a>
A list of tags to associate with the stack that is created or updated. CloudFormation also propagates these tags to resources in the stack that support it.

`--template-file, --template, -t PATH`  <a name="sam-cli-command-reference-sam-sync-options-template-file"></a>
The path and file name where your AWS SAM template is located.  
If you specify this option, then AWS SAM deploys only the template and the local resources that it points to.

`--use-container, -u`  <a name="sam-cli-command-reference-sam-sync-options-use-container"></a>
If your functions depend on packages that have natively compiled dependencies, use this option to build your function inside an AWS Lambda-like Docker container.  
Currently, this option is not compatible with `--dependency-layer`. If you use `--use-container` with `--dependency-layer`, the AWS SAM CLI informs you and continues with `--no-dependency-layer`.

`--watch`  <a name="sam-cli-command-reference-sam-sync-options-watch"></a>
Starts a process that watches your local application for changes and automatically syncs them to the AWS Cloud. By default, when you specify this option, AWS SAM syncs all resources in your application as you update them. With this option, AWS SAM performs an initial CloudFormation deployment. Then, AWS SAM uses AWS service APIs to update code resources. AWS SAM uses CloudFormation to update infrastructure resources when you update your AWS SAM template.

`--watch-exclude TEXT`  <a name="sam-cli-command-reference-sam-sync-options-watch-exclude"></a>
Excludes a file or folder from being observed for file changes. To use this option, `--watch` must also be provided.  
This option receives a key-value pair:  
+ **Key** – The logical ID of a Lambda function in your application.
+ **Value** – The associated file name or folder to exclude.
When you update any files or folders specified with the `--watch-exclude` option, the AWS SAM CLI will not initiate a sync. However, when an update to other files or folders initiates a sync, these files or folders will be included in that sync.  
You can provide this option multiple times in a single command.

## Examples
<a name="sam-cli-command-reference-sam-sync-examples"></a>

For examples on using this command, refer to [Options for the sam sync command](using-sam-cli-sync.md#using-sam-cli-sync-options).

# sam traces
<a name="sam-cli-command-reference-sam-traces"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam traces` command.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam traces` command fetches AWS X-Ray traces in your AWS account in the AWS Region.

## Usage
<a name="sam-cli-command-reference-sam-traces-usage"></a>

```
$ sam traces <options>
```

## Options
<a name="sam-cli-command-reference-sam-traces-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-traces-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-sam-traces-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "`samconfig.toml`" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--end-time TEXT`  <a name="sam-cli-command-reference-sam-traces-options-end-time"></a>
Fetches traces up to this time. The time can be relative values like '5mins ago', 'tomorrow', or a formatted timestamp like '2018-01-01 10:10:10'.

`--output TEXT`  <a name="sam-cli-command-reference-sam-traces-options-output"></a>
Specifies the output format for logs. To print formatted logs, specify `text`. To print the logs as JSON, specify `json`.

`--save-params`  <a name="sam-cli-command-reference-sam-traces-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--start-time TEXT`  <a name="sam-cli-command-reference-sam-traces-options-start-time"></a>
Fetches traces starting at this time. The time can be relative values like '5mins ago', 'yesterday', or a formatted timestamp like '2018-01-01 10:10:10'. It defaults to '10mins ago'.

`--tail`  <a name="sam-cli-command-reference-sam-traces-options-tail"></a>
Tails the trace output. This ignores the end time argument and continues to display traces as they become available.

`--trace-id TEXT`  <a name="sam-cli-command-reference-sam-traces-options-trace-id"></a>
The unique identifier for an X-Ray trace.

## Examples
<a name="sam-cli-command-reference-sam-traces-examples"></a>

Run the following command to fetch X-Ray traces by ID.

```
$ sam traces --trace-id tracing-id-1 --trace-id tracing-id-2
```

Run the following command to tail X-Ray traces as they become available.

```
$ sam traces --tail
```

# sam validate
<a name="sam-cli-command-reference-sam-validate"></a>

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam validate` command.

For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)

The `sam validate` command verifies whether an AWS SAM template file is valid.

## Usage
<a name="sam-cli-command-reference-sam-validate-usage"></a>

```
$ sam validate <options>
```

## Options
<a name="sam-cli-command-reference-sam-validate-options"></a>

`--config-env TEXT`  <a name="sam-cli-command-reference-sam-validate-options-config-env"></a>
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="sam-cli-command-reference-sam-validate-options-config-file"></a>
The path and file name of the configuration file containing default parameter values to use. The default value is "samconfig.toml" in the root of the project directory. For more information about configuration files, see [AWS SAM CLI configuration file](serverless-sam-cli-config.md).

`--debug`  <a name="sam-cli-command-reference-sam-validate-options-debug"></a>
Turns on debug logging to print debug message generated by the AWS SAM CLI and display timestamps.

`--lint`  <a name="sam-cli-command-reference-sam-validate-options-lint"></a>
 Run linting validation on template through **cfn-lint**. Create a `cfnlintrc` config file to specify additional parameters. For more information, see [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) in the *CloudFormation GitHub repository*. 

`--profile TEXT`  <a name="sam-cli-command-reference-sam-validate-options-profile"></a>
The specific profile from your credential file that gets AWS credentials.

`--region TEXT`  <a name="sam-cli-command-reference-sam-validate-options-region"></a>
The AWS Region to deploy to. For example, us-east-1.

`--save-params`  <a name="sam-cli-command-reference-sam-validate-options-save-params"></a>
Save the parameters that you provide at the command line to the AWS SAM configuration file.

`--template-file, --template, -t PATH`  <a name="sam-cli-command-reference-sam-validate-options-template-file"></a>
 The AWS SAM template file. Default value is `template.[yaml|yml]`.   
 If your template is in your current working directory and is named `template.[yaml|yml|json]`, this option is not required.   
 If you just ran **sam build**, this option is not required. 

## Example
<a name="sam-cli-command-reference-sam-validate-examples"></a>

For an example on using this command to validate a template, refer to [Validate AWS SAM template files](serverless-sam-cli-using-validate.md).

For an example on using this command with cfn-lint, refer to [Validate your AWS SAM applications with CloudFormation Linter](validate-cfn-lint.md).

# AWS SAM CLI management
<a name="reference-sam-cli"></a>

This section contains information on ways you can manage and customize your version of the AWS SAM CLI. This includes information on how you can configure AWS SAM CLI command parameter values using a project-level configuration file. It also includes information on managing different versions of your AWS SAM CLI, setting AWS credentials so that AWS SAM can make calls to AWS services on your behalf, and different ways you can customize AWS SAM. This section ends with a section on general AWS SAM troubleshooting.

**Topics**
+ [

# AWS SAM CLI configuration file
](serverless-sam-cli-config.md)
+ [

# Managing AWS SAM CLI versions
](manage-sam-cli-versions.md)
+ [

# Setting up AWS credentials
](serverless-getting-started-set-up-credentials.md)
+ [

# Telemetry in the AWS SAM CLI
](serverless-sam-telemetry.md)
+ [

# AWS SAM CLI troubleshooting
](sam-cli-troubleshooting.md)

# AWS SAM CLI configuration file
<a name="serverless-sam-cli-config"></a>

The AWS Serverless Application Model Command Line Interface (AWS SAM CLI) supports a project-level configuration file that you can use to configure AWS SAM CLI command parameter values.

For documentation on creating and using configuration files, see [Configuring the AWS SAM CLI](using-sam-cli-configure.md).

**Topics**
+ [

## Default configuration file settings
](#serverless-sam-cli-config-default)
+ [

## Supported configuration file formats
](#serverless-sam-cli-config-formats)
+ [

## Specify a configuration file
](#serverless-sam-cli-config-specify)
+ [

## Configuration file basics
](#serverless-sam-cli-config-basics)
+ [

## Parameter value rules
](#serverless-sam-cli-config-rules)
+ [

## Configuration precedence
](#serverless-sam-cli-config-precedence)
+ [

## Creating and modifying configuration files
](#serverless-sam-cli-config-using)

## Default configuration file settings
<a name="serverless-sam-cli-config-default"></a>

AWS SAM uses the following default configuration file settings:
+ **Name** – `samconfig`.
+ **Location** – At the root of your project. This is the same location as your `template.yaml` file.
+ **Format** – `TOML`. To learn more, see [TOML](https://toml.io/en/) in the *TOML documentation*.

The following is an example project structure that includes the default configuration file name and location:

```
sam-app
├── README.md
├── __init__.py
├── events
├── hello_world
├── samconfig.toml
├── template.yaml
└── tests
```

The following is an example `samconfig.toml` 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
```

## Supported configuration file formats
<a name="serverless-sam-cli-config-formats"></a>

`TOML` and `[YAML|YML]` formats are supported. See the following basic syntax:

### TOML
<a name="serverless-sam-cli-config-formats-toml"></a>

```
version = 0.1
[environment]
[environment.command]
[environment.command.parameters]
option = parameter value
```

### YAML
<a name="serverless-sam-cli-config-formats-yaml"></a>

```
version: 0.1
environment:
  command:
    parameters:
      option: parameter value
```

## Specify a configuration file
<a name="serverless-sam-cli-config-specify"></a>

By default, the AWS SAM CLI looks for a configuration file in the following order:

1. **Custom configuration file** – If you use the `--config-file` option to specify a file name and location, the AWS SAM CLI looks for this file first.

1. **Default `samconfig.toml` file** – This is the default configuration file name and format, located at the root of your project. If you don’t specify a custom configuration file, the AWS SAM CLI looks for this file next.

1. **`samconfig.[yaml|yml]` file** – If the `samconfig.toml` does not exist at the root of your project, the AWS SAM CLI looks for this file.

The following is an example of specifying a custom configuration file using the `--config-file` option:

```
$ sam deploy --config-file myconfig.yaml
```

**Note**  
The `--config-file` parameter must be relative to the location of the AWS SAM template file because the AWS SAM CLI needs to determine the context in which the configuration is applied. The `samconfig.toml` file manages configuration settings for your version of the AWS SAM CLI, and the CLI looks for the `samconfig.toml` file (or the overriden config file parameter) in the relative the folder of the `template.yaml` file.

## Configuration file basics
<a name="serverless-sam-cli-config-basics"></a>

### Environment
<a name="serverless-sam-cli-config-basics-environment"></a>

An **environment** is a named identifier that contains a unique set of configuration settings. You can have multiple environments in a single AWS SAM application.

The default environment name is `default`.

Use the AWS SAM CLI `--config-env` option to specify the environment to use.

### Command
<a name="serverless-sam-cli-config-basics-command"></a>

The **command** is the AWS SAM CLI command to specify parameter values for.

To specify parameter values for all commands, use the `global` identifier.

When referencing an AWS SAM CLI command, replace spaces (` `) and hyphens (`–`) with underscores (`_`). See the following examples:
+ `build`
+ `local_invoke`
+ `local_start_api`

### Parameters
<a name="serverless-sam-cli-config-basics-parameters"></a>

**Parameters** are specified as key-value pairs.
+ The **key** is the AWS SAM CLI command option name.
+ The **value** is the value to specify.

When specifying keys, use the long-form command option name and replace hyphens (`–`) with underscores (`_`). The following are examples:
+ `region`
+ `stack_name`
+ `template_file`

## Parameter value rules
<a name="serverless-sam-cli-config-rules"></a>

### TOML
<a name="serverless-sam-cli-config-rules-toml"></a>
+ Boolean values can be `true` or `false`. For example, `confirm_changeset = true`.
+ For string values, use quotation marks (`""`). For example, `region = "us-west-2"`.
+ For list values, use quotation marks (`""`) and separate each value using a space (` `). For example: `capabilities = "CAPABILITY_IAM CAPABILITY_NAMED_IAM"`.
+ For values that contain a list of key-value pairs, the pairs are space-delimited (` `) and the value of each pair is surrounded by encoded quotation marks (`\" \"`). For example, `tags = "project=\"my-application\" stage=\"production\""`.
+ For parameter values that can be specified multiple times, the value is an array of arguments. For example: `image_repositories = ["my-function-1=image-repo-1", "my-function-2=image-repo-2"]`.

### YAML
<a name="serverless-sam-cli-config-rules-yaml"></a>
+ Boolean values can be `true` or `false`. For example, `confirm_changeset: true`.
+ For entries that contain a single string value, quotation marks (`""`) are optional. For example, `region: us-west-2`. This includes entries that contain multiple key-value pairs that are provided as a single string. The following is an example:

  ```
  $ sam deploy --tags "foo=bar hello=world"
  ```

  ```
  default:
    deploy:
      parameters:
        tags: foo=bar hello=world
  ```
+ For entries that contain a list of values, or entries that can be used multiple times in a single command, specify them as a list of strings.

  The following is an example:

  ```
  $ sam remote invoke --parameter "InvocationType=Event" --parameter "LogType=None"
  ```

  ```
  default:
    remote_invoke:
      parameters:
          parameter:
          - InvocationType=Event
          - LogType=None
  ```

## Configuration precedence
<a name="serverless-sam-cli-config-precedence"></a>

When configuring values, the following precedence takes place:
+ Parameter values that you provide at the command line take precedence over corresponding values in the configuration file and `Parameters` section of the template file.
+ If the `--parameter-overrides` option is used at the command line or in your configuration file with the `parameter_overrides` key, its values take precedence over values in the `Parameters` section of the template file.
+ In your configuration file, entries provided for a specific command take precedence over global entries. In the following example, the `sam deploy` command will use the stack name `my-app-stack`.

------
#### [ TOML ]

  ```
  [default.global.parameters]
  stack_name = "common-stack"
  
  [default.deploy.parameters]
  stack_name = "my-app-stack"
  ```

------
#### [ YAML ]

  ```
  default:
    global:
      parameters:
        stack_name: common-stack
    deploy:
      parameters:
        stack_name: my-app-stack
  ```

------

## Creating and modifying configuration files
<a name="serverless-sam-cli-config-using"></a>

### Creating configuration files
<a name="serverless-sam-cli-config-using-create"></a>

When you create an application using `sam init`, a default `samconfig.toml` file is created. You can also manually create your configuration file.

### Modifying configuration files
<a name="serverless-sam-cli-config-using-modify"></a>

You can manually modify your configuration files. Also, during any AWS SAM CLI interactive flow, configured values will be displayed in brackets (`[ ]`). If you modify these values, the AWS SAM CLI will update your configuration file.

The following is an example interactive flow using the `sam deploy --guided` command:

```
$ 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
```

When modifying your configuration file, the AWS SAM CLI handles global values as follows:
+ If the parameter value exists in the `global` section of your configuration file, the AWS SAM CLI doesn’t write the value to the specific command section.
+ If the parameter value exists in both the `global` and specific command sections, the AWS SAM CLI deletes the specific entry in favor of the global value.

# Managing AWS SAM CLI versions
<a name="manage-sam-cli-versions"></a>

Manage your AWS Serverless Application Model Command Line Interface (AWS SAM CLI) versions through upgrading, downgrading, and uninstalling. Optionally, you can download and install the AWS SAM CLI nightly build.

**Topics**
+ [

## Upgrading the AWS SAM CLI
](#manage-sam-cli-versions-upgrade)
+ [

## Uninstalling the AWS SAM CLI
](#manage-sam-cli-versions-uninstall)
+ [

## Switch from using Homebrew to manage the AWS SAM CLI
](#manage-sam-cli-versions-switch)
+ [

## Managing the AWS SAM CLI nightly build
](#manage-sam-cli-versions-nightly-build)
+ [

## Installing the AWS SAM CLI into a virtual environment using pip
](#manage-sam-cli-versions-install-virtual)
+ [

## Managing the AWS SAM CLI with Homebrew
](#manage-sam-cli-versions-homebrew)
+ [

## Troubleshooting
](#manage-sam-cli-versions-troubleshoot)

## Upgrading the AWS SAM CLI
<a name="manage-sam-cli-versions-upgrade"></a>

### Linux
<a name="manage-sam-cli-versions-upgrade-linux"></a>

To upgrade the AWS SAM CLI on Linux, follow the installation instructions in [Installing the AWS SAM CLI](install-sam-cli.md#install-sam-cli-instructions), but add the `--update` option to the install command, as follows:

```
sudo ./sam-installation/install --update
```

### macOS
<a name="manage-sam-cli-versions-upgrade-macos"></a>

The AWS SAM CLI must be upgraded through the same method used to install it. We recommend that you use the package installer to install and upgrade the AWS SAM CLI.

 To upgrade the AWS SAM CLI using the package installer, install the latest package version. For instructions, see [Installing the AWS SAM CLI](install-sam-cli.md#install-sam-cli-instructions). 

### Windows
<a name="manage-sam-cli-versions-upgrade-windows"></a>

To upgrade the AWS SAM CLI, repeat the Windows installation steps in [Install the AWS SAM CLI](install-sam-cli.md) again.

## Uninstalling the AWS SAM CLI
<a name="manage-sam-cli-versions-uninstall"></a>

### Linux
<a name="manage-sam-cli-versions-uninstall-linux"></a>

To uninstall the AWS SAM CLI on Linux, you must delete the symlink and installation directory by running the following commands:

1. Locate the symlink and install paths.
   + Find the symlink using the **which** command:

     ```
     which sam
     ```

     The output shows the path where the AWS SAM binaries are located, for example:

     ```
      /usr/local/bin/sam
     ```
   + Find the directory that the symlink points to using the **ls** command:

     ```
     ls -l /usr/local/bin/sam
     ```

     In the following example, the installation directory is `/usr/local/aws-sam-cli`.

     ```
      lrwxrwxrwx 1 ec2-user ec2-user 49 Oct 22 09:49 /usr/local/bin/sam -> /usr/local/aws-sam-cli/current/bin/sam
     ```

1. Delete the symlink.

   ```
   sudo rm /usr/local/bin/sam
   ```

1. Delete the installation directory.

   ```
   sudo rm -rf /usr/local/aws-sam-cli
   ```

### macOS
<a name="manage-sam-cli-versions-uninstall-macos"></a>

Uninstall the AWS SAM CLI through the same method that was used to install it. We recommend that you use the package installer to install the AWS SAM CLI.

If you installed the AWS SAM CLI using the package installer, follow these steps to uninstall.

**To uninstall the AWS SAM CLI**

1.  Remove the AWS SAM CLI program by modifying and running the following: 

   ```
   $ sudo rm -rf /path-to/aws-sam-cli
   ```

   1.  *sudo* – If your user has write permissions to where the AWS SAM CLI program is installed, **sudo** is not required. Otherwise, **sudo** is required. 

   1.  */path-to* – Path to where you installed the AWS SAM CLI program. The default location is `/usr/local`. 

1.  Remove the AWS SAM CLI `$PATH` by modifying and running the following: 

   ```
   $ sudo rm -rf /path-to-symlink-directory/sam
   ```

   1.  *sudo* – If your user has write permissions to `$PATH`, **sudo** is not required. Otherwise, **sudo** is required. 

   1.  *path-to-symlink-directory* – Your `$PATH` environment variable. The default location is `/usr/local/bin`. 

1.  Verify that the AWS SAM CLI is uninstalled by running the following: 

   ```
   $ sam --version
   command not found: sam
   ```

### Windows
<a name="manage-sam-cli-versions-uninstall-windows"></a>

To uninstall the AWS SAM CLI using Windows Settings, follow these steps:

1. From the Start menu, search for "Add or remove programs".

1. Choose the result named **AWS SAM Command Line Interface**, and then choose **Uninstall** to launch the uninstaller.

1. Confirm that you want to uninstall the AWS SAM CLI.

## Switch from using Homebrew to manage the AWS SAM CLI
<a name="manage-sam-cli-versions-switch"></a>

If you use Homebrew to install and upgrade the AWS SAM CLI, we recommend using an AWS supported method. Follow these instructions to switch to a supported method.

**To switch from using Homebrew**

1. Follow instructions at [Uninstalling a Homebrew installed AWS SAM CLI](#manage-sam-cli-versions-homebrew-uninstall) to uninstall the Homebrew managed version.

1. Follow instructions at [Install the AWS SAM CLI](install-sam-cli.md) to install the AWS SAM CLI using a supported method.

## Managing the AWS SAM CLI nightly build
<a name="manage-sam-cli-versions-nightly-build"></a>

You can download and install the AWS SAM CLI nightly build. It contains a pre-release version of the AWS SAM CLI code that may be less stable than the production version. When installed, you can use the nightly build with the `sam-nightly` command. You can install and use both the production and nightly build versions of the AWS SAM CLI at the same time.

**Note**  
The nightly build does not contain a pre-release version of the build image. Because of that, building your serverless application with the **--use-container** option uses the latest production version of the build image.

### Installing the AWS SAM CLI nightly build
<a name="manage-sam-cli-versions-nightly-build-install"></a>

To install the AWS SAM CLI nightly build, follow these instructions.

#### Linux
<a name="manage-sam-cli-versions-nightly-build-install-linux"></a>

You can install the nightly build version of the AWS SAM CLI on the Linux x86\$164 platform using the package installer.

**To install the AWS SAM CLI nightly build**

1. Download the package installer from [sam-cli-nightly](https://github.com/aws/aws-sam-cli/releases/sam-cli-nightly/) in the *aws-sam-cli GitHub repository*.

1. Follow the steps for [installing the AWS SAM CLI](install-sam-cli.md) to install the nightly build package.

#### macOS
<a name="manage-sam-cli-versions-nightly-build-install-macos"></a>

You can install the nightly build version of the AWS SAM CLI on macOS, using the nightly build package installer.

**To install the AWS SAM CLI nightly build**

1. Download the package installer for your platform from [sam-cli-nightly](https://github.com/aws/aws-sam-cli/releases/sam-cli-nightly/) in the *aws-sam-cli GitHub repository*.

1. Follow the steps for [installing the AWS SAM CLI](install-sam-cli.md) to install the nightly build package.

#### Windows
<a name="manage-sam-cli-versions-nightly-build-windows"></a>

The nightly build version of the AWS SAM CLI is available with this download link: [AWS SAM CLI nightly build](https://github.com/aws/aws-sam-cli/releases/download/sam-cli-nightly/AWS_SAM_CLI_64_PY3.msi). To install the nightly build on Windows, perform the same steps as in the [Install the AWS SAM CLI](install-sam-cli.md), but use the nightly build download link instead.

To verify that you have installed the nightly build version, run the **sam-nightly --version** command. The output of this command is in the form `1.X.Y.dev<YYYYMMDDHHmm>`, for example:

```
SAM CLI, version 1.20.0.dev202103151200
```

### Switch from Homebrew to the package installer
<a name="manage-sam-cli-versions-nightly-build-switch"></a>

If you are using Homebrew to install and upgrade the AWS SAM CLI nightly build and would like to switch to using the package installer, follow these steps.

**To switch from Homebrew to the package installer**

1. Uninstall the Homebrew installed AWS SAM CLI nightly build.

   ```
   $ brew uninstall aws-sam-cli-nightly
   ```

1. Verify that the AWS SAM CLI nightly build is uninstalled by running the following:

   ```
   $ sam-nightly --version
   zsh: command not found: sam-nightly
   ```

1. Follow steps in the previous section to install the AWS SAM CLI nightly build.

## Installing the AWS SAM CLI into a virtual environment using pip
<a name="manage-sam-cli-versions-install-virtual"></a>

We recommend using the native package installer to install the AWS SAM CLI. If you must use pip, we recommend that you install the AWS SAM CLI into a virtual environment. This ensures a clean installation environment and an isolated environment if errors occur.

**Note**  
As of October 24, 2023, the AWS SAM CLI is discontinuing support for Python 3.7. To learn more, see [AWS SAM CLI discontinuing support for Python 3.7](important-notes.md#important-notes-2023-10-python).

**To install the AWS SAM CLI into a virtual environment**

1. From a starting directory of your choice, create a virtual environment and name it.

------
#### [ Linux / macOS ]

   ```
   $ mkdir project
   $ cd project
   $ python3 -m venv venv
   ```

------
#### [ Windows ]

   ```
   > mkdir project
   > cd project
   > py -3 -m venv venv
   ```

------

1. Activate the virtual environment

------
#### [ Linux / macOS ]

   ```
   $ . venv/bin/activate
   ```

   The prompt changes to show you that your virtual environment is active.

   ```
   (venv) $ 
   ```

------
#### [ Windows ]

   ```
   > venv\Scripts\activate
   ```

   The prompt changes to show you that your virtual environment is active.

   ```
   (venv) > 
   ```

------

1. Install the AWS SAM CLI into your virtual environment.

   ```
   (venv) $ pip install --upgrade aws-sam-cli
   ```

1. Verify that the AWS SAM CLI is installed correctly.

   ```
   (venv) $ sam --version
   SAM CLI, version 1.94.0
   ```

1. You can use the `deactivate` command to exit the virtual environment. Whenever you start a new session, you must reactivate the environment.

## Managing the AWS SAM CLI with Homebrew
<a name="manage-sam-cli-versions-homebrew"></a>

**Note**  
Starting September 2023, AWS will no longer maintain the AWS managed Homebrew installer for the AWS SAM CLI (`aws/tap/aws-sam-cli`). To continue using Homebrew, you can use the community managed installer (`aws-sam-cli`). From September 2023, any Homebrew command that references `aws/tap/aws-sam-cli` will redirect to `aws-sam-cli`.  
We recommend that you use our supported [installation](install-sam-cli.md) and [upgrade](#manage-sam-cli-versions-upgrade) methods.

### Installing the AWS SAM CLI using Homebrew
<a name="manage-sam-cli-versions-homebrew-install"></a>

**Note**  
These instructions use the community managed AWS SAM CLI Homebrew installer. For further support, see the *[homebrew-core](https://github.com/Homebrew/homebrew-core/issues) repository*.

**To install the AWS SAM CLI**

1. Run the following:

   ```
   $ brew install aws-sam-cli
   ```

1. Verify the installation:

   ```
   $ sam --version
   ```

   After successful installation of the AWS SAM CLI, you should see output like the following:

   ```
   SAM CLI, version 1.94.0
   ```

### Upgrading the AWS SAM CLI using Homebrew
<a name="manage-sam-cli-versions-homebrew-upgrade"></a>

To upgrade the AWS SAM CLI using Homebrew, run the following command:

```
$ brew upgrade aws-sam-cli
```

### Uninstalling a Homebrew installed AWS SAM CLI
<a name="manage-sam-cli-versions-homebrew-uninstall"></a>

If the AWS SAM CLI was installed using Homebrew, follow these steps to uninstall it.

**To uninstall the AWS SAM CLI**

1. Run the following:

   ```
   $ brew uninstall aws-sam-cli
   ```

1. Verify that the AWS SAM CLI is uninstalled by running the following:

   ```
   $ sam --version
   command not found: sam
   ```

### Switching to the community managed Homebrew installer
<a name="manage-sam-cli-versions-homebrew-switch"></a>

If you are using the AWS managed Homebrew installer (`aws/tap/aws-sam-cli`) and prefer to continue using Homebrew, we recommend switching to the community managed Homebrew installer (`aws-sam-cli`).

To switch in a single command, run the following:

```
$ brew uninstall aws-sam-cli && brew untap aws/tap && brew cleanup aws/tap && brew update && brew install aws-sam-cli
```

Follow these instructions to run each command individually.

**To switch to the community managed Homebrew installer**

1. Uninstall the AWS managed Homebrew version of the AWS SAM CLI:

   ```
   $ brew uninstall aws-sam-cli
   ```

1. Verify that the AWS SAM CLI has been uninstalled:

   ```
   $ which sam
   sam not found
   ```

1. Remove the AWS managed AWS SAM CLI tap:

   ```
   $ brew untap aws/tap
   ```

   If you receive an error like the following, add the `--force` option and try again.

   ```
   Error: Refusing to untap aws/tap because it contains the following installed formulae or casks:
   aws-sam-cli-nightly
   ```

1. Remove cached files for the AWS managed installer:

   ```
   $ brew cleanup aws/tap
   ```

1. Update Homebrew and all formulae:

   ```
   $ brew update
   ```

1. Install the community managed version of the AWS SAM CLI:

   ```
   $ brew install aws-sam-cli
   ```

1. Verify that the AWS SAM CLI is successfully installed:

   ```
   $ sam --version
   SAM CLI, version 1.94.0
   ```

## Troubleshooting
<a name="manage-sam-cli-versions-troubleshoot"></a>

If you come across errors when installing or using the AWS SAM CLI, see [AWS SAM CLI troubleshooting](sam-cli-troubleshooting.md).

# Setting up AWS credentials
<a name="serverless-getting-started-set-up-credentials"></a>

The AWS SAM command line interface (CLI) requires you to set AWS credentials so that it can make calls to AWS services on your behalf. For example, the AWS SAM CLI makes calls to Amazon S3 and CloudFormation.

You might have already set AWS credentials to work with AWS tools, like one of the AWS SDKs or the AWS CLI. If you haven't, this topic shows you the recommended approaches for setting AWS credentials.

To set AWS credentials, you must have the *access key ID* and your *secret access key* for the IAM user you want to configure. For information about access key IDs and secret access keys, see [Managing Access Keys for IAM Users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) in the *IAM User Guide*.

Next, determine whether you have the AWS CLI installed. Then follow the instructions in one of the following sections:

## Using the AWS CLI
<a name="serverless-getting-started-set-up-credentials-cli"></a>

If you have the AWS CLI installed, use the `aws configure` command and follow the prompts:

```
$ aws configure
AWS Access Key ID [None]: your_access_key_id
AWS Secret Access Key [None]: your_secret_access_key
Default region name [None]: 
Default output format [None]:
```

For information about the `aws configure` command, see [Quickly Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html#cli-quick-configuration) in the *AWS Command Line Interface User Guide*.

## Not using the AWS CLI
<a name="serverless-getting-started-set-up-credentials-no-cli"></a>

If you don't have the AWS CLI installed, you can either create a credentials file or set environment variables:
+ **Credentials file** – You can set credentials in the AWS credentials file on your local system. This file must be located in one of the following locations:
  + `~/.aws/credentials` on Linux or macOS
  + `C:\Users\USERNAME\.aws\credentials` on Windows

  This file should contain lines in the following format:

  ```
  [default]
  aws_access_key_id = your_access_key_id
  aws_secret_access_key = your_secret_access_key
  ```

   
+ **Environment variables** – You can set the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.

  To set these variables on Linux or macOS, use the **export** command:

  ```
  export AWS_ACCESS_KEY_ID=your_access_key_id
  export AWS_SECRET_ACCESS_KEY=your_secret_access_key
  ```

  To set these variables on Windows, use the **set** command:

  ```
  set AWS_ACCESS_KEY_ID=your_access_key_id
  set AWS_SECRET_ACCESS_KEY=your_secret_access_key
  ```

# Telemetry in the AWS SAM CLI
<a name="serverless-sam-telemetry"></a>

At AWS, we develop and launch services based on what we learn from interactions with customers. We use customer feedback to iterate on our product. Telemetry is additional information that helps us to better understand our customers' needs, diagnose issues, and deliver features that improve the customer experience.

The AWS SAM command line interface (CLI) collects telemetry, such as generic usage metrics, system and environment information, and errors. For details about the types of telemetry collected, see [Types of information collected](#serverless-sam-telemtry-data-collected).

The AWS SAM CLI does **not** collect personal information, such as user names or email addresses. It also does not extract sensitive project-level information.

Customers control whether telemetry is turned on, and they can change their settings at any point of time. If telemetry remains on, the AWS SAM CLI sends telemetry data in the background without requiring any additional customer interaction.

## Turn off telemetry for a session
<a name="serverless-sam-telemtry-opt-out"></a>

In macOS and Linux operating systems, you can turn off telemetry for a single session. To turn off telemetry for your current session, run the following command to set the environment variable `SAM_CLI_TELEMETRY` to `false`. Repeat the command for each new terminal or session.

```
export SAM_CLI_TELEMETRY=0
```

## Turn off telemetry for your profile in all sessions
<a name="serverless-sam-telemtry-opt-out-profile"></a>

Run the following commands to turn off telemetry for all sessions when you're running the AWS SAM CLI on your operating system.

### To turn off telemetry in Linux
<a name="w2aac28c19c16c15b5"></a>

1. Run:

   ```
   echo "export SAM_CLI_TELEMETRY=0" >>~/.profile
   ```

1. Run:

   ```
   source ~/.profile
   ```

### To turn off telemetry in macOS
<a name="w2aac28c19c16c15b7"></a>

1. Run:

   ```
   echo "export SAM_CLI_TELEMETRY=0" >>~/.profile
   ```

1. Run:

   ```
   source ~/.profile
   ```

### To turn off telemetry in Windows
<a name="w2aac28c19c16c15b9"></a>

You can set the environment variable temporarily for the lifetime of the terminal window with the following command:

If using Command Prompt:

```
set SAM_CLI_TELEMETRY=0
```

If using PowerShell:

```
$env:SAM_CLI_TELEMETRY=0
```

To set the environment variable permanently in either the Command Prompt or PowerShell, use the following command:

```
setx SAM_CLI_TELEMETRY 0
```

**Note**  
Changes will not go into effect until the terminal has been closed and reopened.

## Types of information collected
<a name="serverless-sam-telemtry-data-collected"></a>
+ **Usage information** – The generic commands and subcommands that customers run.
+ **Errors and diagnostic information** – The status and duration of commands that customers run, including exit codes, internal exception names, and failures when connecting to Docker.
+ **System and environment information** – The Python version, operating system (Windows, Linux, or macOS), environment in which the AWS SAM CLI runs (for example, AWS CodeBuild, an AWS IDE toolkit, or a terminal), and hash values of usage attributes.

## Learn more
<a name="serverless-sam-telemtry-learn-more"></a>

The telemetry data that the AWS SAM CLI collects adheres to the AWS data privacy policies. For more information, see the following:
+ [AWS Service Terms](https://aws.amazon.com/service-terms/)
+ [Data Privacy FAQ](https://aws.amazon.com/compliance/data-privacy-faq/)

# AWS SAM CLI troubleshooting
<a name="sam-cli-troubleshooting"></a>

This section provides details on how to troubleshoot error messages when using, installing, and managing the AWS Serverless Application Model Command Line Interface (AWS SAM CLI).

**Topics**
+ [

## Troubleshooting
](#install-sam-cli-troubleshooting)
+ [

## Error messages
](#sam-cli-troubleshoot-messages)
+ [

## Warning messages
](#sam-cli-troubleshoot-warning)

## Troubleshooting
<a name="install-sam-cli-troubleshooting"></a>

For troubleshooting guidance related to AWS SAM CLI, see [Troubleshooting installation errors](install-sam-cli.md#sam-cli-troubleshoot-install).

## Error messages
<a name="sam-cli-troubleshoot-messages"></a>

### Curl error: "curl: (6) Could not resolve: ..."
<a name="sam-cli-troubleshoot-messages-curl"></a>

When trying to invoke the API Gateway endpoint, you see the following error:

```
curl: (6) Could not resolve: endpointdomain (Domain name not found)
```

This means that you've attempted to send a request to a domain that's not valid. This can happen if your serverless application failed to deploy successfully, or if you have a typo in your **curl** command. Verify that the application deployed successfully by using the CloudFormation console or the AWS CLI, and verify that your **curl** command is correct.

### Error: Can’t find exact resource information with given stack name
<a name="sam-cli-troubleshoot-messages-exact-resource"></a>

When running the `sam remote invoke` command on an application that contains a single Lambda function resource, you see the following error:

```
Error: Can't find exact resource information with given <stack-name>. Please provide full resource ARN or --stack-name to resolve the ambiguity.
```

**Possible cause: You didn’t provide the `--stack-name` option.**  
If a function ARN is not provided as an argument, the `sam remote invoke` command requires that the `--stack-name` option is provided.

**Solution: Provide the `--stack-name` option.**  
The following is an example:  

```
$ sam remote invoke --stack-name sam-app

Invoking Lambda Function HelloWorldFunction                                                                                                                                                                                                                     
START RequestId: 40593abb-e1ad-4d99-87bd-ac032e364e82 Version: $LATEST
END RequestId: 40593abb-e1ad-4d99-87bd-ac032e364e82
REPORT RequestId: 40593abb-e1ad-4d99-87bd-ac032e364e82  Duration: 11.31 ms      Billed Duration: 12 ms  Memory Size: 128 MB     Max Memory Used: 67 MB  Init Duration: 171.71 ms
{"statusCode":200,"body":"{\"message\":\"hello world\"}"}%
```

### Error: Can’t find resource information from stack name
<a name="sam-cli-troubleshoot-messages-stack-name"></a>

When running the `sam remote invoke` command and passing a Lambda function ARN as an argument, you see the following error:

```
Error: Can't find resource information from stack name (<stack-name>) and resource id (<function-id>)
```

**Possible cause: You have the stack name value defined in your `samconfig.toml` file.**  
The AWS SAM CLI first checks your `samconfig.toml` file for a stack name. If specified, the argument is passed as a logical ID value.

**Solution: Pass the function’s logical ID instead.**  
You can pass the function’s logical ID as an argument instead of the function’s ARN.

**Solution: Remove the stack name value from your configuration file.**  
You can remove the stack name value from your configuration file. This prevents the AWS SAM CLI from passing your function ARN as a logical ID value.  
Run `sam build` after modifying your configuration file.

### Error: Failed to create managed resources: Unable to locate credentials
<a name="sam-cli-troubleshoot-messages-credentials"></a>

When running the **sam deploy** command, you see the following error:

```
Error: Failed to create managed resources: Unable to locate credentials
```

This means that you have not set up AWS credentials to enable the AWS SAM CLI to make AWS service calls. To fix this, you must set up AWS credentials. For more information, see [Setting up AWS credentials](serverless-getting-started-set-up-credentials.md).

### Error: FileNotFoundError in Windows
<a name="sam-cli-troubleshoot-messages-filenotfound-win"></a>

When running commands in AWS SAM CLI on Windows, you may see the following error:

```
Error: FileNotFoundError
```

Possible cause: The AWS SAM CLI might interact with filepaths that exceed the Windows max path limitation.

Solution: To resolve this issue, the new long paths behavior must enabled. To do this, see [Enable Long Paths in Windows 10, Version 1607, and Later](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell#enable-long-paths-in-windows-10-version-1607-and-later) in the *Microsoft Windows App Development Documentation*.

### Error: pip's dependency resolver ...
<a name="sam-cli-troubleshoot-messages-pip"></a>

*Example error text*:

```
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. 
aws-sam-cli 1.58.0 requires aws-sam-translator==1.51.0, but you have aws-sam-translator 1.58.0 which is incompatible. 
aws-sam-cli 1.58.0 requires typing-extensions==3.10.0.0, but you have typing-extensions 4.4.0 which is incompatible.
```

**Possible cause: If you use pip to install packages, dependencies between packages may conflict.**  
Each version of the `aws-sam-cli` package depends on a version of the `aws-sam-translator` package. For example, `aws-sam-cli` v1.58.0 may depend on `aws-sam-translator` v1.51.0.  
If you install the AWS SAM CLI using pip, then install another package which depends on a newer version of `aws-sam-translator`, the following will occur:  
+ The newer version of `aws-sam-translator` will install.
+ The current version of `aws-sam-cli` and the newer version of `aws-sam-translator` may not be compatible.
+ When you use the AWS SAM CLI, the dependency resolver error will occur.

**Solutions:**

1. Use the AWS SAM CLI native package installer.

   1. Uninstall the AWS SAM CLI using pip. For instructions, see [Uninstalling the AWS SAM CLI](manage-sam-cli-versions.md#manage-sam-cli-versions-uninstall).

   1. Install the AWS SAM CLI using the native package installer. For instructions, see [Install the AWS SAM CLI](install-sam-cli.md).

   1. When necessary, upgrade the AWS SAM CLI using the native package installer. For instructions, see [Upgrading the AWS SAM CLI](manage-sam-cli-versions.md#manage-sam-cli-versions-upgrade).

1. If you must use pip, we recommend that you install the AWS SAM CLI into a virtual environment. This ensures a clean installation environment and an isolated environment if errors occur. For instructions, see [Installing the AWS SAM CLI into a virtual environment using pip](manage-sam-cli-versions.md#manage-sam-cli-versions-install-virtual).

### Error: No such command ‘remote’
<a name="sam-cli-troubleshoot-messages-command-remote"></a>

When running the `sam remote invoke` command, you see the following error:

```
$ sam remote invoke ...
2023-06-20 08:15:07 Command remote not available
Usage: sam [OPTIONS] COMMAND [ARGS]...
Try 'sam -h' for help.

Error: No such command 'remote'.
```

**Possible cause: Your version of the AWS SAM CLI is out of date.**  
The AWS SAM CLI `sam remote invoke` command was released with AWS SAM CLI version 1.88.0. You can check your version by running the `sam --version` command.

**Solution: Upgrade your AWS SAM CLI to the latest version.**  
For instructions, see [Upgrading the AWS SAM CLI](manage-sam-cli-versions.md#manage-sam-cli-versions-upgrade).

### Error: Running AWS SAM projects locally requires Docker. Have you got it installed?
<a name="sam-cli-troubleshoot-messages-docker"></a>

When running the **sam local start-api** command, you see the following error:

```
Error: Running AWS SAM projects locally requires Docker. Have you got it installed?
```

This means that you do not have Docker properly installed. Docker is required to test your application locally. To fix this, follow the instructions for installing Docker for your development host. For more information, see [Installing Docker](install-docker.md).

### Error: Security Constraints Not Satisfied
<a name="sam-cli-troubleshoot-messages-security-constraints"></a>

When running **sam deploy --guided**, you're prompted with the question `Function may not have authorization defined, Is this okay? [y/N]`. If you respond to this prompt with **N** (the default response), you see the following error:

```
Error: Security Constraints Not Satisfied
```

The prompt is informing you that the application you're about to deploy might have a publicly accessible Amazon API Gateway API configured without authorization. By responding **N** to this prompt, you're saying that this is not OK.

To fix this, you have the following options:
+ Configure your application with authorization. For information about configuring authorization, see [Control API access with your AWS SAM template](serverless-controlling-access-to-apis.md).
+ If your intention is to have a publicly accessible API endpoint without authorization, restart your deployment and respond to this question with **Y** to indicate that you're OK with deploying.

### message: Missing Authentication Token
<a name="sam-cli-troubleshoot-messages-auth-token"></a>

When trying to invoke the API Gateway endpoint, you see the following error:

```
{"message":"Missing Authentication Token"}
```

This means that you've attempted to send a request to the correct domain, but the URI isn't recognizable. To fix this, verify the full URL, and update the **curl** command with the correct URL.

## Warning messages
<a name="sam-cli-troubleshoot-warning"></a>

### Warning: ... AWS will no longer maintain the Homebrew installer for AWS SAM ...
<a name="sam-cli-troubleshoot-warning-homebrew"></a>

When installing the AWS SAM CLI using Homebrew, you see the following warning message:

```
Warning: ... AWS will no longer maintain the Homebrew installer for AWS SAM (aws/tap/aws-sam-cli). 
				For AWS supported installations, use the first party installers ...
```

**Potential cause: AWS no longer maintaining Homebrew support.**  
Starting September 2023, AWS will no longer maintain the Homebrew installer for the AWS SAM CLI.  

**Solution: Use an AWS supported installation method.**
+ You can find AWS supported installation methods at [Install the AWS SAM CLI](install-sam-cli.md).

**Solution: To continue using Homebrew, use the community managed installer.**
+ You can use the community managed Homebrew installer at your discretion. For instructions, see [Managing the AWS SAM CLI with Homebrew](manage-sam-cli-versions.md#manage-sam-cli-versions-homebrew).

# AWS SAM connector reference
<a name="reference-sam-connector"></a>

This section contains reference information for the AWS Serverless Application Model (AWS SAM) connector resource type. For an introduction to connectors, see [Managing resource permissions with AWS SAM connectors](managing-permissions-connectors.md).

## Supported source and destination resource types for connectors
<a name="supported-connector-resource-types"></a>

The `AWS::Serverless::Connector` resource type supports a select number of connections between source and destination resources. When configuring connectors in your AWS SAM template, use the following table to reference supported connections and the properties that need to be defined for each source and destination resource type. For more information about configuring connectors in your template, see [AWS::Serverless::Connector](sam-resource-connector.md).

For both source and destination resources, when defined within the same template, use the `Id` property. Optionally, a `Qualifier` can be added to narrow the scope of your defined resource. When the resource is not within the same template, use a combination of supported properties.

 To request new connections, [submit a new issue](https://github.com/aws/serverless-application-model/issues/new?assignees=&labels=area%2Fconnectors,stage%2Fneeds-triage&template=other.md&title=%28New%20Connector%20Profile%29) at the *serverless-application-model AWS GitHub repository*.


| Source type | Destination type | Permissions | Source properties | Destination properties | 
| --- | --- | --- | --- | --- | 
| `AWS::ApiGateway::RestApi` | `AWS::Lambda::Function` | `Write` | `Id` or `Qualifier`, `ResourceId`, and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::ApiGateway::RestApi` | `AWS::Serverless::Function` | `Write` | `Id` or `Qualifier`, `ResourceId`, and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::ApiGatewayV2::Api` | `AWS::Lambda::Function` | `Write` | `Id` or `Qualifier`, `ResourceId`, and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::ApiGatewayV2::Api` | `AWS::Serverless::Function` | `Write` | `Id` or `Qualifier`, `ResourceId`, and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::AppSync::DataSource` | `AWS::DynamoDB::Table` | `Read` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::AppSync::DataSource` | `AWS::DynamoDB::Table` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::AppSync::DataSource` | `AWS::Events::EventBus` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::AppSync::DataSource` | `AWS::Lambda::Function` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::AppSync::DataSource` | `AWS::Serverless::Function` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::AppSync::DataSource` | `AWS::Serverless::SimpleTable` | `Read` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::AppSync::DataSource` | `AWS::Serverless::SimpleTable` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::AppSync::GraphQLApi` | `AWS::Lambda::Function` | `Write` | `Id` or `ResourceId` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::AppSync::GraphQLApi` | `AWS::Serverless::Function` | `Write` | `Id` or `ResourceId` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::DynamoDB::Table` | `AWS::Lambda::Function` | `Read` | `Id` or `Arn` and `Type` | `Id` or `RoleName` and `Type` | 
| `AWS::DynamoDB::Table` | `AWS::Serverless::Function` | `Read` | `Id` or `Arn` and `Type` | `Id` or `RoleName` and `Type` | 
| `AWS::Events::Rule` | `AWS::Events::EventBus` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Events::Rule` | `AWS::Lambda::Function` | `Write` | `Id` or `Arn` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Events::Rule` | `AWS::Serverless::Function` | `Write` | `Id` or `Arn` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Events::Rule` | `AWS::Serverless::StateMachine` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Events::Rule` | `AWS::SNS::Topic` | `Write` | `Id` or `Arn` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Events::Rule` | `AWS::SQS::Queue` | `Write` | `Id` or `Arn` and `Type` | `Id` or `Arn`, `QueueUrl`, and `Type` | 
| `AWS::Events::Rule` | `AWS::StepFunctions::StateMachine` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Lambda::Function` | `AWS::DynamoDB::Table` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Lambda::Function` | `AWS::Events::EventBus` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Lambda::Function` | `AWS::Lambda::Function` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Lambda::Function` | `AWS::Location::PlaceIndex` | `Read` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Lambda::Function` | `AWS::S3::Bucket` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Lambda::Function` | `AWS::Serverless::Function` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Lambda::Function` | `AWS::Serverless::SimpleTable` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Lambda::Function` | `AWS::Serverless::StateMachine` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn`, `Name`, and `Type` | 
| `AWS::Lambda::Function` | `AWS::SNS::Topic` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Lambda::Function` | `AWS::SQS::Queue` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Lambda::Function` | `AWS::StepFunctions::StateMachine` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn`, `Name`, and `Type` | 
| `AWS::S3::Bucket` | `AWS::Lambda::Function` | `Write` | `Id` or `Arn` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::S3::Bucket` | `AWS::Serverless::Function` | `Write` | `Id` or `Arn` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Api` | `AWS::Lambda::Function` | `Write` | `Id` or `Qualifier`, `ResourceId`, and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Api` | `AWS::Serverless::Function` | `Write` | `Id` or `Qualifier`, `ResourceId`, and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Function` | `AWS::DynamoDB::Table` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Function` | `AWS::Events::EventBus` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Function` | `AWS::Lambda::Function` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Function` | `AWS::S3::Bucket` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Function` | `AWS::Serverless::Function` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Function` | `AWS::Serverless::SimpleTable` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Function` | `AWS::Serverless::StateMachine` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn`, `Name`, and `Type` | 
| `AWS::Serverless::Function` | `AWS::SNS::Topic` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Function` | `AWS::SQS::Queue` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::Function` | `AWS::StepFunctions::StateMachine` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn`, `Name`, and `Type` | 
| `AWS::Serverless::HttpApi` | `AWS::Lambda::Function` | `Write` | `Id` or `Qualifier`, `ResourceId`, and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::HttpApi` | `AWS::Serverless::Function` | `Write` | `Id` or `Qualifier`, `ResourceId`, and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::SimpleTable` | `AWS::Lambda::Function` | `Read` | `Id` or `Arn` and `Type` | `Id` or `RoleName` and `Type` | 
| `AWS::Serverless::SimpleTable` | `AWS::Serverless::Function` | `Read` | `Id` or `Arn` and `Type` | `Id` or `RoleName` and `Type` | 
| `AWS::Serverless::StateMachine` | `AWS::DynamoDB::Table` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::StateMachine` | `AWS::Events::EventBus` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::StateMachine` | `AWS::Lambda::Function` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::StateMachine` | `AWS::S3::Bucket` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::StateMachine` | `AWS::Serverless::Function` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::StateMachine` | `AWS::Serverless::SimpleTable` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::StateMachine` | `AWS::Serverless::StateMachine` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn`, `Name`, and `Type` | 
| `AWS::Serverless::StateMachine` | `AWS::SNS::Topic` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::StateMachine` | `AWS::SQS::Queue` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::Serverless::StateMachine` | `AWS::StepFunctions::StateMachine` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn`, `Name`, and `Type` | 
| `AWS::SNS::Topic` | `AWS::Lambda::Function` | `Write` | `Id` or `Arn` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::SNS::Topic` | `AWS::Serverless::Function` | `Write` | `Id` or `Arn` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::SNS::Topic` | `AWS::SQS::Queue` | `Write` | `Id` or `Arn` and `Type` | `Id` or `Arn`, `QueueUrl`, and `Type` | 
| `AWS::SQS::Queue` | `AWS::Lambda::Function` | `Read`, `Write` | `Id` or `Arn` and `Type` | `Id` or `RoleName` and `Type` | 
| `AWS::SQS::Queue` | `AWS::Serverless::Function` | `Read`, `Write` | `Id` or `Arn` and `Type` | `Id` or `RoleName` and `Type` | 
| `AWS::StepFunctions::StateMachine` | `AWS::DynamoDB::Table` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::StepFunctions::StateMachine` | `AWS::Events::EventBus` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::StepFunctions::StateMachine` | `AWS::Lambda::Function` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::StepFunctions::StateMachine` | `AWS::S3::Bucket` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::StepFunctions::StateMachine` | `AWS::Serverless::Function` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::StepFunctions::StateMachine` | `AWS::Serverless::SimpleTable` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::StepFunctions::StateMachine` | `AWS::Serverless::StateMachine` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn`, `Name`, and `Type` | 
| `AWS::StepFunctions::StateMachine` | `AWS::SNS::Topic` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::StepFunctions::StateMachine` | `AWS::SQS::Queue` | `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn` and `Type` | 
| `AWS::StepFunctions::StateMachine` | `AWS::StepFunctions::StateMachine` | `Read`, `Write` | `Id` or `RoleName` and `Type` | `Id` or `Arn`, `Name`, and `Type` | 

## IAM policies created by connectors
<a name="reference-sam-connector-policies"></a>

This section documents the AWS Identity and Access Management (IAM) policies that are created by AWS SAM when using connectors.

`AWS::DynamoDB::Table` to `AWS::Lambda::Function`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Lambda::Function` role.  
**Access categories**  
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:DescribeStream",
        "dynamodb:GetRecords",
        "dynamodb:GetShardIterator",
        "dynamodb:ListStreams"
      ],
      "Resource": [
        "%{Source.Arn}/stream/*"
      ]
    }
  ]
}
```

`AWS::Events::Rule` to `AWS::SNS::Topic`  
**Policy type**  
[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sns-topicpolicy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sns-topicpolicy.html) attached to the `AWS::SNS::Topic`.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "events.amazonaws.com"
      },
      "Resource": "%{Destination.Arn}",
      "Action": "sns:Publish",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "%{Source.Arn}"
        }
      }
    }
  ]
}
```

`AWS::Events::Rule` to `AWS::Events::EventBus`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Events::Rule` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "events:PutEvents"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::Events::Rule` to `AWS::StepFunctions::StateMachine`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Events::Rule` role.   
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "states:StartExecution"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::Events::Rule` to `AWS::Lambda::Function`  
**Policy type**  
`[AWS::Lambda::Permission](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html)` attached to the `AWS::Lambda::Function`.  
**Access categories**  
`Write`  

```
{
  "Action": "lambda:InvokeFunction",
  "Principal": "events.amazonaws.com",
  "SourceArn": "%{Source.Arn}"
}
```

`AWS::Events::Rule` to `AWS::SQS::Queue`  
**Policy type**  
`[AWS::SQS::QueuePolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sqs-queuepolicy.html)` attached to the `AWS::SQS::Queue`.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "events.amazonaws.com"
      },
      "Resource": "%{Destination.Arn}",
      "Action": "sqs:SendMessage",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "%{Source.Arn}"
        }
      }
    }
  ]
}
```

`AWS::Lambda::Function` to `AWS::Lambda::Function`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Lambda::Function` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:InvokeAsync",
        "lambda:InvokeFunction"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::Lambda::Function` to `AWS::S3::Bucket`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Lambda::Function` role.  
**Access categories**  
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectAcl",
        "s3:GetObjectLegalHold",
        "s3:GetObjectRetention",
        "s3:GetObjectTorrent",
        "s3:GetObjectVersion",
        "s3:GetObjectVersionAcl",
        "s3:GetObjectVersionForReplication",
        "s3:GetObjectVersionTorrent",
        "s3:ListBucket",
        "s3:ListBucketMultipartUploads",
        "s3:ListBucketVersions",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}/*"
      ]
    }
  ]
}
```
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:AbortMultipartUpload",
        "s3:DeleteObject",
        "s3:DeleteObjectVersion",
        "s3:PutObject",
        "s3:PutObjectLegalHold",
        "s3:PutObjectRetention",
        "s3:RestoreObject"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}/*"
      ]
    }
  ]
}
```

`AWS::Lambda::Function` to `AWS::DynamoDB::Table`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Lambda::Function` role.  
**Access categories**  
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:Query",
        "dynamodb:Scan",
        "dynamodb:BatchGetItem",
        "dynamodb:ConditionCheckItem",
        "dynamodb:PartiQLSelect"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}/index/*"
      ]
    }
  ]
}
```
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:PutItem",
        "dynamodb:UpdateItem",
        "dynamodb:DeleteItem",
        "dynamodb:BatchWriteItem",
        "dynamodb:PartiQLDelete",
        "dynamodb:PartiQLInsert",
        "dynamodb:PartiQLUpdate"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}/index/*"
      ]
    }
  ]
}
```

`AWS::Lambda::Function` to `AWS::SQS::Queue`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Lambda::Function` role.  
**Access categories**  
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:ReceiveMessage",
        "sqs:GetQueueAttributes"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:DeleteMessage",
        "sqs:SendMessage",
        "sqs:ChangeMessageVisibility",
        "sqs:PurgeQueue"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::Lambda::Function` to `AWS::SNS::Topic`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Lambda::Function` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sns:Publish"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::Lambda::Function` to `AWS::StepFunctions::StateMachine`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Lambda::Function` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "states:StartExecution",
        "states:StartSyncExecution"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "states:StopExecution"
      ],
      "Resource": [
        "arn:${AWS::Partition}:states:${AWS::Region}:${AWS::AccountId}:execution:%{Destination.Name}:*"
      ]
    }
  ]
}
```
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "states:DescribeStateMachine",
        "states:ListExecutions"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "states:DescribeExecution",
        "states:DescribeStateMachineForExecution",
        "states:GetExecutionHistory"
      ],
      "Resource": [
        "arn:${AWS::Partition}:states:${AWS::Region}:${AWS::AccountId}:execution:%{Destination.Name}:*"
      ]
    }
  ]
}
```

`AWS::Lambda::Function` to `AWS::Events::EventBus`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Lambda::Function` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "events:PutEvents"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::Lambda::Function` to `AWS::Location::PlaceIndex`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Lambda::Function` role.  
**Access categories**  
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "geo:DescribePlaceIndex",
        "geo:GetPlace",
        "geo:SearchPlaceIndexForPosition",
        "geo:SearchPlaceIndexForSuggestions",
        "geo:SearchPlaceIndexForText"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::ApiGatewayV2::Api` to `AWS::Lambda::Function`  
**Policy type**  
`[AWS::Lambda::Permission](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html)` attached to the `AWS::Lambda::Function`.  
**Access categories**  
`Write`  

```
{
  "Action": "lambda:InvokeFunction",
  "Principal": "apigateway.amazonaws.com",
  "SourceArn": "arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:%{Source.ResourceId}/%{Source.Qualifier}"
}
```

`AWS::ApiGateway::RestApi` to `AWS::Lambda::Function`  
**Policy type**  
`[AWS::Lambda::Permission](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html)` attached to the `AWS::Lambda::Function`.  
**Access categories**  
`Write`  

```
{
  "Action": "lambda:InvokeFunction",
  "Principal": "apigateway.amazonaws.com",
  "SourceArn": "arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:%{Source.ResourceId}/%{Source.Qualifier}"
}
```

`AWS::SNS::Topic` to `AWS::SQS::Queue`  
**Policy type**  
`[AWS::SQS::QueuePolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sqs-queuepolicy.html)` attached to the `AWS::SQS::Queue`.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "sns.amazonaws.com"
      },
      "Resource": "%{Destination.Arn}",
      "Action": "sqs:SendMessage",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "%{Source.Arn}"
        }
      }
    }
  ]
}
```

`AWS::SNS::Topic` to `AWS::Lambda::Function`  
**Policy type**  
`[AWS::Lambda::Permission](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html)` attached to the `AWS::Lambda::Function`.  
**Access categories**  
`Write`  

```
{
  "Action": "lambda:InvokeFunction",
  "Principal": "sns.amazonaws.com",
  "SourceArn": "%{Source.Arn}"
}
```

`AWS::SQS::Queue` to `AWS::Lambda::Function`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::Lambda::Function` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:DeleteMessage"
      ],
      "Resource": [
        "%{Source.Arn}"
      ]
    }
  ]
}
```
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:ReceiveMessage",
        "sqs:GetQueueAttributes"
      ],
      "Resource": [
        "%{Source.Arn}"
      ]
    }
  ]
}
```

`AWS::S3::Bucket` to `AWS::Lambda::Function`  
**Policy type**  
`[AWS::Lambda::Permission](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html)` attached to the `AWS::Lambda::Function`.  
**Access categories**  
`Write`  

```
{
  "Action": "lambda:InvokeFunction",
  "Principal": "s3.amazonaws.com",
  "SourceArn": "%{Source.Arn}",
  "SourceAccount": "${AWS::AccountId}"
}
```

`AWS::StepFunctions::StateMachine` to `AWS::Lambda::Function`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::StepFunctions::StateMachine` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:InvokeAsync",
        "lambda:InvokeFunction"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::StepFunctions::StateMachine` to `AWS::SNS::Topic`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::StepFunctions::StateMachine` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sns:Publish"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::StepFunctions::StateMachine` to `AWS::SQS::Queue`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::StepFunctions::StateMachine` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:SendMessage"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::StepFunctions::StateMachine` to `AWS::S3::Bucket`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::StepFunctions::StateMachine` role.  
**Access categories**  
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectAcl",
        "s3:GetObjectLegalHold",
        "s3:GetObjectRetention",
        "s3:GetObjectTorrent",
        "s3:GetObjectVersion",
        "s3:GetObjectVersionAcl",
        "s3:GetObjectVersionForReplication",
        "s3:GetObjectVersionTorrent",
        "s3:ListBucket",
        "s3:ListBucketMultipartUploads",
        "s3:ListBucketVersions",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}/*"
      ]
    }
  ]
}
```
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:AbortMultipartUpload",
        "s3:DeleteObject",
        "s3:DeleteObjectVersion",
        "s3:PutObject",
        "s3:PutObjectLegalHold",
        "s3:PutObjectRetention",
        "s3:RestoreObject"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}/*"
      ]
    }
  ]
}
```

`AWS::StepFunctions::StateMachine` to `AWS::DynamoDB::Table`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::StepFunctions::StateMachine` role.  
**Access categories**  
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:Query",
        "dynamodb:Scan",
        "dynamodb:BatchGetItem",
        "dynamodb:ConditionCheckItem",
        "dynamodb:PartiQLSelect"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}/index/*"
      ]
    }
  ]
}
```
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:PutItem",
        "dynamodb:UpdateItem",
        "dynamodb:DeleteItem",
        "dynamodb:BatchWriteItem",
        "dynamodb:PartiQLDelete",
        "dynamodb:PartiQLInsert",
        "dynamodb:PartiQLUpdate"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}/index/*"
      ]
    }
  ]
}
```

`AWS::StepFunctions::StateMachine` to `AWS::StepFunctions::StateMachine`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::StepFunctions::StateMachine` role.  
**Access categories**  
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "states:DescribeExecution"
      ],
      "Resource": [
        "arn:${AWS::Partition}:states:${AWS::Region}:${AWS::AccountId}:execution:%{Destination.Name}:*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "events:DescribeRule"
      ],
      "Resource": [
        "arn:${AWS::Partition}:events:${AWS::Region}:${AWS::AccountId}:rule/StepFunctionsGetEventsForStepFunctionsExecutionRule"
      ]
    }
  ]
}
```
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "states:StartExecution"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "states:StopExecution"
      ],
      "Resource": [
        "arn:${AWS::Partition}:states:${AWS::Region}:${AWS::AccountId}:execution:%{Destination.Name}:*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "events:PutTargets",
        "events:PutRule"
      ],
      "Resource": [
        "arn:${AWS::Partition}:events:${AWS::Region}:${AWS::AccountId}:rule/StepFunctionsGetEventsForStepFunctionsExecutionRule"
      ]
    }
  ]
}
```

`AWS::StepFunctions::StateMachine` to `AWS::Events::EventBus`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::StepFunctions::StateMachine` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "events:PutEvents"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::AppSync::DataSource` to `AWS::DynamoDB::Table`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::AppSync::DataSource` role.  
**Access categories**  
`Read`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:Query",
        "dynamodb:Scan",
        "dynamodb:BatchGetItem",
        "dynamodb:ConditionCheckItem",
        "dynamodb:PartiQLSelect"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}/index/*"
      ]
    }
  ]
}
```
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:PutItem",
        "dynamodb:UpdateItem",
        "dynamodb:DeleteItem",
        "dynamodb:BatchWriteItem",
        "dynamodb:PartiQLDelete",
        "dynamodb:PartiQLInsert",
        "dynamodb:PartiQLUpdate"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}/index/*"
      ]
    }
  ]
}
```

`AWS::AppSync::DataSource` to `AWS::Lambda::Function`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::AppSync::DataSource` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:InvokeAsync",
        "lambda:InvokeFunction"
      ],
      "Resource": [
        "%{Destination.Arn}",
        "%{Destination.Arn}:*"
      ]
    }
  ]
}
```

`AWS::AppSync::DataSource` to `AWS::Events::EventBus`  
**Policy type**  
[Customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) attached to the `AWS::AppSync::DataSource` role.  
**Access categories**  
`Write`  

```
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "events:PutEvents"
      ],
      "Resource": [
        "%{Destination.Arn}"
      ]
    }
  ]
}
```

`AWS::AppSync::GraphQLApi` to `AWS::Lambda::Function`  
**Policy type**  
`[AWS::Lambda::Permission](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html)` attached to the `AWS::Lambda::Function`.  
**Access categories**  
`Write`  

```
{
  "Action": "lambda:InvokeFunction",
  "Principal": "appsync.amazonaws.com",
  "SourceArn": "arn:${AWS::Partition}:appsync:${AWS::Region}:${AWS::AccountId}:apis/%{Source.ResourceId}"
}
```

# Installing Docker to use with the AWS SAM CLI
<a name="install-docker"></a>

Docker is an application that runs containers on your machine. With Docker, AWS SAM can provide a local environment similar to AWS Lambda as a container to build, test, and debug your serverless applications.

**Note**  
Docker is required only for testing your applications locally and for building deployment packages using the `--use-container` option.

**Topics**
+ [

## Installing Docker
](#install-docker-instructions)
+ [

## Next steps
](#install-docker-next-steps)

## Installing Docker
<a name="install-docker-instructions"></a>

Follow these instructions to install Docker on your operating system.

### Linux
<a name="install-docker-instructions-linux"></a>

Docker is available on many different operating systems, including most modern Linux distributions, such as CentOS, Debian, and Ubuntu. For information about installing Docker on your particular operating system, see [Get Docker](https://docs.docker.com/get-docker/) on the Docker Docs website.

**To install Docker on Amazon Linux 2 or Amazon Linux 2023**

1. Update the installed packages and package cache on your instance.

   ```
   $ sudo yum update -y
   ```

1. Install the most recent Docker Community Edition package.
   + For Amazon Linux 2, run the following:

     ```
     $ sudo amazon-linux-extras install docker
     ```
   + For Amazon Linux 2023, run the following:

     ```
     $ sudo yum install -y docker
     ```

1. Start the Docker service.

   ```
   $ sudo service docker start
   ```

1. Add the `ec2-user` to the `docker` group so that you can run Docker commands without using **sudo**.

   ```
   $ sudo usermod -a -G docker ec2-user
   ```

1. Pick up the new `docker` group permissions by logging out and logging back in again. To do this, close your current SSH terminal window and reconnect to your instance in a new one. Your new SSH session should have the appropriate `docker` group permissions.

1. Verify that the `ec2-user` can run Docker commands without using **sudo**.

   ```
   $ docker ps
   ```

   You should see the following output, confirming that Docker is installed and running:

   ```
    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
   ```

**Note**  
On Linux, to build and run Lambda functions with a different instruction set architecture than your host machine, there are additional steps to configure Docker. For example, to run `arm64` functions on an `x86_64` machine, you can run the following command to configure the Docker daemon: `docker run --rm --privileged multiarch/qemu-user-static --reset -p yes`.

If you run into issues installing Docker, see [Troubleshooting installation errors](install-sam-cli.md#sam-cli-troubleshoot-install). Or, see the [Troubleshooting](https://docs.docker.com/engine/install/linux-postinstall/#troubleshooting) section of **Post-installation steps for Linux** on the Docker Docs website.

### macOS
<a name="install-docker-instructions-macos"></a>

**Note**  
Docker Desktop is officially supported, but starting with AWS SAM CLI version 1.47.0, you can use alternatives as long as they use the Docker runtime.

1. Install Docker

   The AWS SAM CLI supports Docker running on macOS Sierra 10.12 or later. For how to install Docker, see [Install Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) on the Docker Docs website.

1. Configure your shared drives

   The AWS SAM CLI requires that the project directory, or any parent directory, is listed in a shared drive. This may require file sharing. For more information, see the [ Volume mounting requires file sharing](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#volume-mounting-requires-file-sharing-for-any-project-directories-outside-of-home) troubleshooting topic at *Docker docs*.

1. Verify the installation

   After Docker is installed, verify that it's working. Also confirm that you can run Docker commands from the command line (for example, `docker ps`). You don't need to install, fetch, or pull any containers—the AWS SAM CLI does this automatically as required.

If you run into issues installing Docker, for more troubleshooting tips, see the [Troubleshoot and diagnose](https://docs.docker.com/docker-for-mac/troubleshoot/) section of the Docker Docs website.

### Windows
<a name="install-docker-instructions-windows"></a>

**Note**  
AWS SAM officially supports Docker Desktop. However, starting with AWS SAM CLI version 1.47.0, you can use alternatives as long as they use the Docker runtime.

1. Install Docker.

   Docker Desktop supports the most recent Windows operating system. For legacy versions of Windows, the Docker Toolbox is available. Choose your version of Windows for the correct Docker installation steps:
   + To install Docker for Windows 10, see [Install Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) on the Docker Docs website.
   + To install Docker for earlier versions of Windows, see [The Docker Toolbox](https://github.com/docker-archive/toolbox) on the Docker Toolbox GitHub repository.

1. Configure your shared drives.

   The AWS SAM CLI requires that the project directory, or any parent directory, is listed in a shared drive. In some cases, you must share your drive for Docker to function properly.

1. Verify the installation.

   After Docker is installed, verify that it's working. Also confirm that you can run Docker commands from the command line (for example, **docker ps**). You don't need to install, fetch, or pull any containers—the AWS SAM CLI does this automatically as required.

If you run into issues installing Docker, for more troubleshooting tips, see the [Troubleshoot and diagnose](https://docs.docker.com/docker-for-mac/troubleshoot/) section of the Docker Docs website.

## Next steps
<a name="install-docker-next-steps"></a>

For how to install the AWS SAM CLI, see [Install the AWS SAM CLI](install-sam-cli.md).

# Installing Finch to use with the AWS SAM CLI
<a name="install-finch"></a>

Finch is AWS's container development tool that provides an alternative to Docker, particularly beneficial on macOS and Linux systems. For more information, see [Finch on GitHub](https://github.com/runfinch). With Finch, AWS SAM can provide a local environment similar to AWS Lambda as a container to build, test, and debug your serverless applications.

**Note**  
You need Finch for testing your applications locally, for building deployment packages using the `--use-container` option, and building OCI image functions. Starting with AWS SAM CLI version 1.145.0, AWS SAM CLI supports Finch as an alternative container runtime to Docker.

**Topics**
+ [

## Installing Finch
](#install-finch-instructions)
+ [

## Configuring Finch with AWS SAM CLI
](#install-finch-configuration)
+ [

## Verifying the installation
](#install-finch-verification)
+ [

## Stopping Finch
](#install-finch-stopping)
+ [

## Troubleshooting
](#install-finch-troubleshooting)
+ [

## Next steps
](#install-finch-next-steps)

## Installing Finch
<a name="install-finch-instructions"></a>

Follow these instructions to install Finch on your operating system.

### Prerequisites
<a name="install-finch-prerequisites"></a>

**Note**  
Finch integration in AWS SAM CLI is available on macOS and Linux systems. For Windows users, consider using a virtual machine or Linux environment for Finch functionality.

**macOS versions:**
+ macOS 15 Sequoia
+ macOS 14 Sonoma

**Note**  
Finch supports the latest two versions of macOS.

**Linux:**
+ Linux Kernel v4.x\$1

### Installing Finch
<a name="install-finch"></a>

#### macOS
<a name="install-finch-instructions-macos"></a>

**To install Finch on macOS**

1. Install Finch using the `brew` CLI. If prompted, enter your macOS password.

   ```
   $ brew install finch
   ```

1. Check the installed Finch version.

   ```
   $ finch --version
   ```

1. Initialize Finch virtual machine (first time setup).

   ```
   $ finch vm init
   ```

1. Start Finch virtual machine.

   ```
   $ finch vm start
   ```

1. Check the status of the Finch virtual machine.

   ```
   $ finch vm status
   ```

1. Verify that Finch runs correctly.

   ```
   $ finch --info
   $ finch ps
   ```

For more information, see [Installing Finch on macOS](https://runfinch.com/docs/managing-finch/macos/installation/).

#### Linux
<a name="install-finch-instructions-linux"></a>

You can install Finch on Amazon Linux, Ubuntu, or by using a generic installation method. For more information, see [Installing Finch on Linux](https://runfinch.com/docs/managing-finch/linux/installation/).

## Configuring Finch with AWS SAM CLI
<a name="install-finch-configuration"></a>

After you install Finch, the AWS SAM CLI automatically detects and uses Finch as a container runtime when Docker does not run.

**Note**  
Finch serves as a fallback to Docker. If you have both Docker and Finch installed and running, AWS SAM CLI prioritizes Docker by default.

### Administrator preference configuration (macOS)
<a name="install-finch-configuration-preference"></a>

You can configure AWS SAM CLI to use a specific container runtime as the default by creating an administrator preference file. This system-wide preference overrides the default fallback behavior.

**Available configuration options**
+ **Set Finch as preferred container runtime:**

  ```
  $ sudo /usr/libexec/PlistBuddy -c "Add :DefaultContainerRuntime string finch" /Library/Preferences/com.amazon.samcli.plist
  ```
+ **Set Docker as preferred container runtime:**

  ```
  $ sudo /usr/libexec/PlistBuddy -c "Add :DefaultContainerRuntime string docker" /Library/Preferences/com.amazon.samcli.plist
  ```
+ **Remove preference (return to default behavior):**

  ```
  $ sudo /usr/libexec/PlistBuddy -c "Remove :DefaultContainerRuntime" /Library/Preferences/com.amazon.samcli.plist
  ```

**Note**  
When no administrator preference is set, AWS SAM CLI uses Docker by default when available, with Finch as a fallback when Docker is not running.

### Directory mounting differences (macOS)
<a name="install-finch-differences"></a>

On macOS, AWS SAM local commands fail if you locate your project outside your home directory (`~`) or `/Volumes`. This design restricts automatic directory mounting for security reasons without your knowledge.

**Mitigation options**
+ **Option 1:** Open the Finch configuration in a text editor `~/.finch/finch.yaml` and add your project path under the `additional_directories` section, then restart the Finch virtual machine. For additional information, see [Finch documentation](https://runfinch.com/docs/managing-finch/macos/disk-management/#adding-additional-disk-mounts).

  ```
  $ finch vm stop
  $ finch vm start
  ```
+ **Option 2:** Move your project to your home directory.

## Verifying the installation
<a name="install-finch-verification"></a>

After you install and start Finch, verify that it works with AWS SAM CLI.

### Basic verification
<a name="install-finch-verification-basic"></a>

Run the following command to verify that AWS SAM CLI can use Finch:

```
$ sam build --use-container
```

You should see AWS SAM CLI using Finch to build your application in a container environment.

**Note**  
Finch serves as a fallback to Docker. If Docker is running, AWS SAM CLI will prioritize Docker by default.

### Testing Finch as a fallback
<a name="install-finch-verification-fallback"></a>

To test Finch as a fallback when Docker is running, you need to stop Docker first.

**To test Finch fallback functionality**

1. Stop Docker using the appropriate commands for your operating system.

   **macOS:**

   ```
   $ docker stop $(docker ps -q)
   $ pkill -f "Docker Desktop"
   ```

   Verify Docker is stopped.

   ```
   $ docker ps
   ```

   **Linux:**

   ```
   $ docker stop $(docker ps -q)
   $ sudo systemctl stop docker
   ```

   Verify Docker is stopped.

   ```
   $ sudo systemctl status docker
   ```

1. Run the `sam build --use-container` command to verify AWS SAM CLI automatically uses Finch as a fallback.

## Stopping Finch
<a name="install-finch-stopping"></a>

If you need to stop Finch, use the following commands:

**macOS:**

```
$ finch vm stop
$ sudo pkill -f finch
```

Verify Finch is stopped.

```
$ finch vm status
```

**Linux:**

```
$ sudo systemctl stop finch
$ sudo pkill -f finch
```

Verify Finch is stopped.

```
$ sudo systemctl status finch
```

## Troubleshooting
<a name="install-finch-troubleshooting"></a>

If you encounter issues with Finch:
+ Verify that your operating system meets the prerequisites.
+ Verify that you have enabled virtualization on your system.
+ For macOS, verify that you have sufficient disk space for the virtual machine.
+ For Linux, verify that you have proper permissions to run `systemctl` commands.
+ If you encounter CloudFormation deployment failures with "media type not supported" errors when you push multi-architecture images to Amazon Elastic Container Registry (Amazon ECR), create a single image artifact instead of using multi-architecture images. This occurs because Finch pushes both the image index and image to Amazon ECR, while Docker pushes only the image.
+ If cross-platform building fails when the target function architecture doesn't match the host machine architecture on Linux, enable cross-platform emulation by running `sudo finch run --privileged --rm tonistiigi/binfmt:master --install all`.

For additional troubleshooting, see the [Finch documentation](https://runfinch.com/docs/) or the [AWS SAM CLI troubleshooting](sam-cli-troubleshooting.md).

## Next steps
<a name="install-finch-next-steps"></a>

Now that you have Finch installed, you can use it with AWS SAM CLI to:
+ Build serverless applications using containers with `sam build --use-container`. For more information, see [sam build](sam-cli-command-reference-sam-build.md).
+ Test Lambda functions locally with `sam local invoke`. For more information, see [sam local invoke](sam-cli-command-reference-sam-local-invoke.md).
+ Start a local API Gateway with `sam local start-api`. For more information, see [sam local start-api](sam-cli-command-reference-sam-local-start-api.md).
+ Start a local Lambda endpoint with `sam local start-lambda`. For more information, see [sam local start-lambda](sam-cli-command-reference-sam-local-start-lambda.md).

For more information about using AWS SAM CLI with containers, see [Default build with AWS SAM](serverless-sam-cli-using-build.md).

# Image repositories for AWS SAM
<a name="serverless-image-repositories"></a>

AWS SAM simplifies continuous integration and continuous delivery (CI/CD) tasks for serverless applications with the help of build container images. The images that AWS SAM provides include the AWS SAM command line interface (CLI) and build tools for a number of supported AWS Lambda runtimes. This make it easier to build and package serverless applications using the AWS SAM CLI. You can use these images with CI/CD systems to automate the building and deployment of AWS SAM applications. For examples, see [Deploy with CI/CD systems and pipelines](deploying-options.md#serverless-deploying-ci-cd).

AWS SAM build container image URIs are tagged with the version of the AWS SAM CLI included in that image. If you specify the untagged URI, then the latest version is used. For example, `public.ecr.aws/sam/build-nodejs20.x` uses the latest image. However, `public.ecr.aws/sam/build-nodejs20.x:1.24.1` uses the the image containing AWS SAM CLI version 1.24.1.

Starting with version 1.33.0 of the AWS SAM CLI, both `x86_64` and `arm64` container images are available for supported runtimes. For more information, see [Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) in the *AWS Lambda Developer Guide*.

**Note**  
Prior to version 1.22.0 of the AWS SAM CLI, DockerHub was the default repository that the AWS SAM CLI pulled the container image from. Starting with version 1.22.0, the default repository changed to Amazon Elastic Container Registry Public (Amazon ECR Public). To pull a container image from a repository other than the current default, you can use the **[sam build](sam-cli-command-reference-sam-build.md)** command with the **--build-image** option. The examples at the end of this topic show how to build applications using DockerHub repository images.

## Image repository URIs
<a name="serverless-image-repository-uris"></a>

The following table lists the URIs of [Amazon ECR Public](https://docs.aws.amazon.com/AmazonECR/latest/public/what-is-ecr.html) build container images that you can use to build and package serverless applications with AWS SAM.

**Note**  
Amazon ECR Public replaced DockerHub starting with the AWS SAM CLI version 1.22.0. If you are using an earlier version of the AWS SAM CLI, we recommend that you upgrade.


| Runtime |  Amazon ECR Public | 
| --- | --- | 
| Custom runtime (AL2023) | [public.ecr.aws/sam/build-provided.al2023](https://gallery.ecr.aws/sam/build-provided.al2023) | 
| Custom runtime (AL2) | [public.ecr.aws/sam/build-provided.al2](https://gallery.ecr.aws/sam/build-provided.al2) | 
| Custom runtime | [public.ecr.aws/sam/build-provided](https://gallery.ecr.aws/sam/build-provided) | 
| Java 25 | [public.ecr.aws/sam/build-java25](https://gallery.ecr.aws/sam/build-java25) | 
| Java 21 | [public.ecr.aws/sam/build-java21](https://gallery.ecr.aws/sam/build-java21) | 
| Java 17 | [public.ecr.aws/sam/build-java17](https://gallery.ecr.aws/sam/build-java17) | 
| Java 11 | [public.ecr.aws/sam/build-java11](https://gallery.ecr.aws/sam/build-java11) | 
| Java 8 | [public.ecr.aws/sam/build-java8](https://gallery.ecr.aws/sam/build-java8) | 
| .NET 9 | [public.ecr.aws/sam/build-dotnet9](https://gallery.ecr.aws/sam/build-dotnet9) | 
| .NET 8 | [public.ecr.aws/sam/build-dotnet8](https://gallery.ecr.aws/sam/build-dotnet8) | 
| .NET 7 | [public.ecr.aws/sam/build-dotnet7](https://gallery.ecr.aws/sam/build-dotnet7) | 
| .NET 6 | [public.ecr.aws/sam/build-dotnet6](https://gallery.ecr.aws/sam/build-dotnet6) | 
| Node.js 24 | [public.ecr.aws/sam/build-nodejs24.x](https://gallery.ecr.aws/sam/build-nodejs24.x) | 
| Node.js 22 | [public.ecr.aws/sam/build-nodejs22.x](https://gallery.ecr.aws/sam/build-nodejs22.x) | 
| Node.js 20 | [public.ecr.aws/sam/build-nodejs20.x](https://gallery.ecr.aws/sam/build-nodejs20.x) | 
| Node.js 18 | [public.ecr.aws/sam/build-nodejs18.x](https://gallery.ecr.aws/sam/build-nodejs18.x) | 
| Node.js 16 | [public.ecr.aws/sam/build-nodejs16.x](https://gallery.ecr.aws/sam/build-nodejs16.x) | 
| Python 3.14 | [public.ecr.aws/sam/build-python3.14](https://gallery.ecr.aws/sam/build-python3.14) | 
| Python 3.13 | [public.ecr.aws/sam/build-python3.13](https://gallery.ecr.aws/sam/build-python3.13) | 
| Python 3.12 | [public.ecr.aws/sam/build-python3.12](https://gallery.ecr.aws/sam/build-python3.12) | 
| Python 3.11 | [public.ecr.aws/sam/build-python3.11](https://gallery.ecr.aws/sam/build-python3.11) | 
| Python 3.10 | [public.ecr.aws/sam/build-python3.10](https://gallery.ecr.aws/sam/build-python3.10) | 
| Python 3.9 | [public.ecr.aws/sam/build-python3.9](https://gallery.ecr.aws/sam/build-python3.9) | 
| Python 3.8 | [public.ecr.aws/sam/build-python3.8](https://gallery.ecr.aws/sam/build-python3.8) | 
| Ruby 3.4 | [public.ecr.aws/sam/build-ruby3.4](https://gallery.ecr.aws/sam/build-ruby3.4) | 
| Ruby 3.3 | [public.ecr.aws/sam/build-ruby3.3](https://gallery.ecr.aws/sam/build-ruby3.3) | 
| Ruby 3.2 | [public.ecr.aws/sam/build-ruby3.2](https://gallery.ecr.aws/sam/build-ruby3.2) | 

## Examples
<a name="serverless-image-repository-example-commands"></a>

The following two example commands build applications using container images from the image repository:

**Build a Node.js 24 application using a container image pulled from Amazon ECR**:

```
$ sam build --use-container --build-image public.ecr.aws/sam/build-nodejs24.x
```

**Build a function resource using the Python 3.14 container image pulled from Amazon ECR**:

```
$ sam build --use-container --build-image Function1=public.ecr.aws/sam/build-python3.14
```

# Deploying serverless applications gradually with AWS SAM
<a name="automating-updates-to-serverless-apps"></a>

AWS Serverless Application Model (AWS SAM) comes built-in with [CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/welcome.html) to provide gradual AWS Lambda deployments. With just a few lines of configuration, AWS SAM does the following for you:
+ Deploys new versions of your Lambda function, and automatically creates aliases that point to the new version.
+ Gradually shifts customer traffic to the new version until you're satisfied that it's working as expected. If an update doesn't work correctly, you can roll back the changes.
+ Defines pre-traffic and post-traffic test functions to verify that the newly deployed code is configured correctly and that your application operates as expected.
+ Automatically rolls back the deployment if CloudWatch alarms are triggered.

**Note**  
If you enable gradual deployments through your AWS SAM template, a CodeDeploy resource is automatically created for you. You can view the CodeDeploy resource directly through the AWS Management Console.

**Example**

The following example demonstrates the use of CodeDeploy to gradually shift customers to your newly deployed version of Lambda function:

```
Resources:
MyLambdaFunction:
  Type: AWS::Serverless::Function
  Properties:
    Handler: index.handler
    Runtime: nodejs20.x
    CodeUri: s3://bucket/code.zip

    AutoPublishAlias: live

    DeploymentPreference:
      Type: Canary10Percent10Minutes 
      Alarms:
        # A list of alarms that you want to monitor
        - !Ref AliasErrorMetricGreaterThanZeroAlarm
        - !Ref LatestVersionErrorMetricGreaterThanZeroAlarm
      Hooks:
        # Validation Lambda functions that are run before & after traffic shifting
        PreTraffic: !Ref PreTrafficLambdaFunction
        PostTraffic: !Ref PostTrafficLambdaFunction
```

These revisions to the AWS SAM template do the following:
+ `AutoPublishAlias`: By adding this property and specifying an alias name, AWS SAM:
  + Detects when new code is being deployed, based on changes to the Lambda function's Amazon S3 URI.
  + Creates and publishes an updated version of that function with the latest code.
  + Creates an alias with a name that you provide (unless an alias already exists), and points to the updated version of the Lambda function. Function invocations should use the alias qualifier to take advantage of this. If you aren't familiar with Lambda function versioning and aliases, see [AWS Lambda Function Versioning and Aliases](https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html).
+ `Deployment Preference Type`: In the previous example, 10 percent of your customer traffic is immediately shifted to your new version. After 10 minutes, all traffic is shifted to the new version. However, if your pre-traffic or post-traffic tests fail, or if a CloudWatch alarm is triggered, CodeDeploy rolls back your deployment. You can specify how traffic should be shifted between versions in the following ways:
  + `Canary`: Traffic is shifted in two increments. You can choose from predefined canary options. The options specify the percentage of traffic that's shifted to your updated Lambda function version in the first increment, and the interval, in minutes, before the remaining traffic is shifted in the second increment. 
  + `Linear`: Traffic is shifted in equal increments with an equal number of minutes between each increment. You can choose from predefined linear options that specify the percentage of traffic that's shifted in each increment and the number of minutes between each increment. 
  + `AllAtOnce`: All traffic is shifted from the original Lambda function to the updated Lambda function version at once. 

  The following table outlines other traffic-shifting options that are available beyond the one used in the example.     
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/automating-updates-to-serverless-apps.html)
+ `Alarms`: These are CloudWatch alarms that are triggered by any errors raised by the deployment. When encountered, they automatically roll back your deployment. For example, if the updated code you're deploying causes errors within the application. Another example is if any [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-functions-metrics.html) or custom CloudWatch metrics that you specified have breached the alarm threshold.
+ `Hooks`: These are pre-traffic and post-traffic test functions that run checks before traffic shifting starts to the new version, and after traffic shifting completes.
  + `PreTraffic`: Before traffic shifting starts, CodeDeploy invokes the pre-traffic hook Lambda function. This Lambda function must call back to CodeDeploy and indicate success or failure. If the function fails, it aborts and reports a failure back to CloudFormation. If the function succeeds, CodeDeploy proceeds to traffic shifting.
  + `PostTraffic`: After traffic shifting completes, CodeDeploy invokes the post-traffic hook Lambda function. This is similar to the pre-traffic hook, where the function must call back to CodeDeploy to report a success or failure. Use post-traffic hooks to run integration tests or other validation actions.

  For more information, see [SAM Reference to Safe Deployments](https://github.com/aws/serverless-application-model/blob/master/docs/safe_lambda_deployments.rst). 

## Gradually deploying a Lambda function for the first time
<a name="automating-updates-to-serverless-apps-first-time"></a>

 When deploying a Lambda function gradually, CodeDeploy requires a previously deployed function version to shift traffic from. Therefore, your first deployment should be accomplished in two steps: 
+ **Step 1**: Deploy your Lambda function and automatically create aliases with `AutoPublishAlias`.
+ **Step 2**: Perform your gradual deployment with `DeploymentPreference`.

Performing your first gradual deployment in two steps gives CodeDeploy a previous Lambda function version to shift traffic from.

### Step 1: Deploy your Lambda function
<a name="automating-updates-to-serverless-apps-first-time-step1"></a>

```
Resources:
MyLambdaFunction:
  Type: AWS::Serverless::Function
  Properties:
    Handler: index.handler
    Runtime: nodejs20.x
    CodeUri: s3://bucket/code.zip

    AutoPublishAlias: live
```

### Step 2: Perform your gradual deployment
<a name="automating-updates-to-serverless-apps-first-time-step2"></a>

```
Resources:
MyLambdaFunction:
  Type: AWS::Serverless::Function
  Properties:
    Handler: index.handler
    Runtime: nodejs20.x
    CodeUri: s3://bucket/code.zip

    AutoPublishAlias: live

    DeploymentPreference:
      Type: Canary10Percent10Minutes 
      Alarms:
        # A list of alarms that you want to monitor
        - !Ref AliasErrorMetricGreaterThanZeroAlarm
        - !Ref LatestVersionErrorMetricGreaterThanZeroAlarm
      Hooks:
        # Validation Lambda functions that are run before and after traffic shifting
        PreTraffic: !Ref PreTrafficLambdaFunction
        PostTraffic: !Ref PostTrafficLambdaFunction
```

## Learn more
<a name="automating-updates-to-serverless-apps-learn"></a>

For a hands-on example of configuring a gradual deployment, see [Module 5 - Canary Deployments](https://s12d.com/sam-ws-en-canaries) in *The Complete AWS SAM Workshop*.

# Important reference notes for AWS SAM
<a name="important-notes"></a>

This section contains important notes and announcements for AWS Serverless Application Model (AWS SAM).

**Topics**
+ [

## Important notes for 2023
](#important-notes-2023)

## Important notes for 2023
<a name="important-notes-2023"></a>

### October 2023
<a name="important-notes-2023-10"></a>

#### AWS SAM CLI discontinuing support for Python 3.7
<a name="important-notes-2023-10-python"></a>

*Published on 2023-10-20*

Python 3.7 received end-of-life status in June of 2023. The AWS SAM CLI will discontinue support for Python 3.7 on October 24, 2023. For more information, see the [announcement](https://github.com/aws/aws-sam-cli/issues/5889) at the *aws-sam-cli GitHub repository*.

This change impacts the following users:
+ If you use Python 3.7 and install the AWS SAM CLI through `pip`.
+ If you use the `aws-sam-cli` as a library and build your application with Python 3.7.

If you install and manage the AWS SAM CLI through another method, you are not affected.

For impacted users, we recommend that you upgrade your development environment to Python 3.8 or newer.

This change does not affect support for the Python 3.7 AWS Lambda runtime environment. For more information, see [Runtime deprecation policy](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html#runtime-support-policy) in the *AWS Lambda Developer Guide*.