# 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).