The AWS Serverless Application Model Command Line Interface (AWS SAM CLI)sam sync command provides options to quickly sync local application changes to the AWS Cloud. Usesam sync when developing your applications to:

Withsam sync, you can create a rapid development workflow that shortens the time it takes to sync your local changes to the cloud for testing and validation.

Thesam sync command is a part of AWS SAM Accelerate.AWS SAM Accelerate provides tools that you can use to speed up the experience of developing and testing serverless applications in the AWS Cloud.

Automatically detect and sync local changes to the AWS Cloud

Runsam sync with the--watch option to begin syncing your application to the AWS Cloud. This does the following:

Since thesam sync command automatically updates your application in the AWS Cloud, it is recommended for development environments only. When you runsam sync, you will be asked to confirm:

**The sync command should only be used against a development stack**.Confirm that you are synchronizing a development stack.Enter Y to proceed with the command, or enter N to cancel: [Y/n]:ENTER

Customize what local changes are synced to the AWS Cloud

Provide options to customize what local changes are synced to the AWS Cloud. This can speed up the time it takes to see your local changes in the cloud for testing and validation.

For example, provide the--code option to sync only code changes, such as AWS Lambda function code. During development, if you are focused specifically on Lambda code, this will get your changes into the cloud quickly for testing and validation. The following is an example:

$sam sync --code --watch

To sync only code changes for a specific Lambda function or layer, use the--resource-id option.The following is an example:

$sam sync --code --resource-idHelloWorldFunction --resource-idHelloWorldLayer

Prepare your application in the cloud for testing and validation

Thesam sync command automatically finds the quickest method available to update your application in the AWS Cloud. This can speed up your development and cloud testing workflows. By utilizing AWS service APIs, you can quickly develop, sync, and test supported resources. For a hands-on example, seeModule 6 - AWS SAM Accelerate inThe Complete AWS SAM Workshop.

Options for the sam sync command

The following are some of the main options you can use to modify thesam sync command. For a listof all options, seesam sync.

Perform a one-time AWS CloudFormation deployment

Use the--no-watch option to turn off automatic syncing. The following is an example:

$sam sync --no-watch

The AWS SAM CLI will perform a one-time AWS CloudFormation deployment. This command groups together the actions performed by thesam build andsam deploy commands.

Skip the initial AWS CloudFormation deployment

You can customize whether an AWS CloudFormation deployment is required each timesam sync is run.

The following is an example:

$sam sync --skip-deploy-sync

Sync a resource from a nested stack

For more information about creating nested applications, seeReuse code and resources using nested applications in AWS SAM.

Specify a specific AWS CloudFormation stack to update

To specify a specific AWS CloudFormation stack to update, provide the--stack-name option. The followingis an example:

$sam sync --stack-namedev-sam-app

Speed up build times by building your project in the source folder

For supported runtimes and build methods, you can use the--build-in-source option to build your project directly in the source folder. By default, the AWS SAM CLI builds in a temporary directory, which involves copying over source code and project files. With--build-in-source, the AWS SAM CLI builds directly in your source folder, which speeds up the build process by removing the need to copy files to a temporary directory.

For a list of supported runtimes and build methods, see--build-in-source.

Specify files and folders that won't initiate a sync

Use the--watch-exclude option to specify any file or folder that won't initiate a sync when updated. For more information about this option, see--watch-exclude.

The following is an example that excludes thepackage-lock.json file associated with ourHelloWorldFunction function:

$sam sync --watch --watch-excludeHelloWorldFunction=package-lock.json

When this command is run, the AWS SAM CLI will initiate the sync process. This includes the following:

When we modify thepackage-lock.json file, the AWS SAM CLI won't initiate a sync. When another file is updated, the AWS SAM CLI will initiate a sync, which will include thepackage-lock.json file.

The following is an example of specifying a Lambda function of a child stack:

$sam sync --watch --watch-excludeChildStackA/MyFunction=database.sqlite3

Troubleshooting

To troubleshoot the AWS SAM CLI, seeAWS SAM CLI troubleshooting.

Examples

Using sam sync to update the Hello World application

In this example, we start by initializing the sample Hello World application. To learn more about this application, seeTutorial: Deploy a Hello World application with AWS SAM.

Runningsam sync begins the build and deployment process.

$sam syncThe SAM CLI will use the AWS Lambda, Amazon API Gateway, and AWS StepFunctions APIs to upload your code withoutperforming a CloudFormation deployment. This will cause drift in your CloudFormation stack.**The sync command should only be used against a development stack**.Confirm that you are synchronizing a development stack.Enter Y to proceed with the command, or enter N to cancel: [Y/n]:Queued infra sync. Waiting for in progress code syncs to complete...Starting infra sync.Manifest file is changed (new hash: 3298f13049d19cffaa37ca931dd4d421) or dependency folder (.aws-sam/deps/0663e6fe-a888-4efb-b908-e2344261e9c7) is missing for (HelloWorldFunction), downloading dependencies and copying/building sourceBuilding codeuri: /Users/.../Demo/sync/sam-app/hello_world runtime: python3.9 metadata:{} architecture: x86_64 functions: HelloWorldFunctionRunning PythonPipBuilder:CleanUpRunning PythonPipBuilder:ResolveDependenciesRunning PythonPipBuilder:CopySourceBuild SucceededSuccessfully packaged artifacts and wrote output template to file /var/folders/45/5ct135bx3fn2551_ptl5g6_80000gr/T/tmpx_5t4u3f.Execute the following command to deploy the packaged templatesam deploy --template-file /var/folders/45/5ct135bx3fn2551_ptl5g6_80000gr/T/tmpx_5t4u3f --stack-name <YOUR STACK NAME>    Deploying with following values    ===============================    Stack name                   : sam-app    Region                       : us-west-2    Disable rollback             : False    Deployment s3 bucket         : aws-sam-cli-managed-default-samclisam-s3-demo-bucket-1a4x26zbcdkqr    Capabilities                 : ["CAPABILITY_NAMED_IAM", "CAPABILITY_AUTO_EXPAND"]    Parameter overrides          :{}    Signing Profiles             : nullInitiating deployment=====================2023-03-17 11:17:19 - Waiting for stack create/update to completeCloudFormation events from stack operations (refresh every 0.5 seconds)---------------------------------------------------------------------------------------------------------------------------------------------ResourceStatus                      ResourceType                        LogicalResourceId                   ResourceStatusReason---------------------------------------------------------------------------------------------------------------------------------------------CREATE_IN_PROGRESS                  AWS::CloudFormation::Stack          sam-app                             Transformation succeededCREATE_IN_PROGRESS                  AWS::CloudFormation::Stack          AwsSamAutoDependencyLayerNestedSt   -                                                                        ackCREATE_IN_PROGRESS                  AWS::IAM::Role                      HelloWorldFunctionRole              -CREATE_IN_PROGRESS                  AWS::IAM::Role                      HelloWorldFunctionRole              Resource creation InitiatedCREATE_IN_PROGRESS                  AWS::CloudFormation::Stack          AwsSamAutoDependencyLayerNestedSt   Resource creation Initiated                                                                        ackCREATE_COMPLETE                     AWS::IAM::Role                      HelloWorldFunctionRole              -CREATE_COMPLETE                     AWS::CloudFormation::Stack          AwsSamAutoDependencyLayerNestedSt   -                                                                        ackCREATE_IN_PROGRESS                  AWS::Lambda::Function               HelloWorldFunction                  -CREATE_IN_PROGRESS                  AWS::Lambda::Function               HelloWorldFunction                  Resource creation InitiatedCREATE_COMPLETE                     AWS::Lambda::Function               HelloWorldFunction                  -CREATE_IN_PROGRESS                  AWS::ApiGateway::RestApi            ServerlessRestApi                   -CREATE_IN_PROGRESS                  AWS::ApiGateway::RestApi            ServerlessRestApi                   Resource creation InitiatedCREATE_COMPLETE                     AWS::ApiGateway::RestApi            ServerlessRestApi                   -CREATE_IN_PROGRESS                  AWS::ApiGateway::Deployment         ServerlessRestApiDeployment47fc2d   -                                                                        5f9dCREATE_IN_PROGRESS                  AWS::Lambda::Permission             HelloWorldFunctionHelloWorldPermi   -                                                                        ssionProdCREATE_IN_PROGRESS                  AWS::Lambda::Permission             HelloWorldFunctionHelloWorldPermi   Resource creation Initiated                                                                        ssionProdCREATE_IN_PROGRESS                  AWS::ApiGateway::Deployment         ServerlessRestApiDeployment47fc2d   Resource creation Initiated                                                                        5f9dCREATE_COMPLETE                     AWS::ApiGateway::Deployment         ServerlessRestApiDeployment47fc2d   -                                                                        5f9dCREATE_IN_PROGRESS                  AWS::ApiGateway::Stage              ServerlessRestApiProdStage          -CREATE_IN_PROGRESS                  AWS::ApiGateway::Stage              ServerlessRestApiProdStage          Resource creation InitiatedCREATE_COMPLETE                     AWS::ApiGateway::Stage              ServerlessRestApiProdStage          -CREATE_COMPLETE                     AWS::Lambda::Permission             HelloWorldFunctionHelloWorldPermi   -                                                                        ssionProdCREATE_COMPLETE                     AWS::CloudFormation::Stack          sam-app                             ----------------------------------------------------------------------------------------------------------------------------------------------CloudFormation outputs from deployed stack----------------------------------------------------------------------------------------------------------------------------------------------Outputs----------------------------------------------------------------------------------------------------------------------------------------------Key                 HelloWorldFunctionIamRoleDescription         Implicit IAM Role created for Hello World functionValue               arn:aws:iam::012345678910:role/sam-app-HelloWorldFunctionRole-BUFVMO2PJIYFKey                 HelloWorldApiDescription         API Gateway endpoint URL for Prod stage for Hello World functionValue               https://pcrx5gdaof.execute-api.us-west-2.amazonaws.com/Prod/hello/Key                 HelloWorldFunctionDescription         Hello World Lambda Function ARNValue               arn:aws:lambda:us-west-2:012345678910:function:sam-app-HelloWorldFunction-2PlN6TPTQoco----------------------------------------------------------------------------------------------------------------------------------------------Stack creation succeeded. Sync infra completed.Infra sync completed.CodeTrigger not created as CodeUri or DefinitionUri is missing for ServerlessRestApi.

Once deployment is complete, we modify theHelloWorldFunction code. The AWS SAM CLI detects this change and syncs our application to the AWS Cloud. Since AWS Lambda supports AWS service APIs, a quick sync is performed.

Syncing Lambda Function HelloWorldFunction...Manifest is not changed for (HelloWorldFunction), running incremental buildBuilding codeuri: /Users/.../Demo/sync/sam-app/hello_world runtime: python3.9 metadata:{} architecture: x86_64 functions: HelloWorldFunctionRunning PythonPipBuilder:CopySourceFinished syncing Lambda Function HelloWorldFunction.

Next, we modify our API endpoint in the application’s AWS SAM template. We change/hello to/helloworld.

AWSTemplateFormatVersion: '2010-09-09'Transform: AWS::Serverless-2016-10-31...Resources:  HelloWorldFunction:    ...    Properties:      ...      Events:        HelloWorld:          Type: Api          Properties:            Path:/helloworld            Method: get

Since the Amazon API Gateway resource doesn’t support the AWS service API, the AWS SAM CLI automatically performs an AWS CloudFormation deployment. The following is an example output:

Queued infra sync. Waiting for in progress code syncs to complete...Starting infra sync.Manifest is not changed for (HelloWorldFunction), running incremental buildBuilding codeuri: /Users/.../Demo/sync/sam-app/hello_world runtime: python3.9 metadata:{} architecture: x86_64 functions: HelloWorldFunctionRunning PythonPipBuilder:CopySourceBuild SucceededSuccessfully packaged artifacts and wrote output template to file /var/folders/45/5ct135bx3fn2551_ptl5g6_80000gr/T/tmpuabo0jb9.Execute the following command to deploy the packaged templatesam deploy --template-file /var/folders/45/5ct135bx3fn2551_ptl5g6_80000gr/T/tmpuabo0jb9 --stack-name <YOUR STACK NAME>    Deploying with following values    ===============================    Stack name                   : sam-app    Region                       : us-west-2    Disable rollback             : False    Deployment s3 bucket         : aws-sam-cli-managed-default-samclisam-s3-demo-bucket-1a4x26zbcdkqr    Capabilities                 : ["CAPABILITY_NAMED_IAM", "CAPABILITY_AUTO_EXPAND"]    Parameter overrides          :{}    Signing Profiles             : nullInitiating deployment=====================2023-03-17 14:41:18 - Waiting for stack create/update to completeCloudFormation events from stack operations (refresh every 0.5 seconds)---------------------------------------------------------------------------------------------------------------------------------------------ResourceStatus                      ResourceType                        LogicalResourceId                   ResourceStatusReason---------------------------------------------------------------------------------------------------------------------------------------------UPDATE_IN_PROGRESS                  AWS::CloudFormation::Stack          sam-app                             Transformation succeededUPDATE_IN_PROGRESS                  AWS::CloudFormation::Stack          AwsSamAutoDependencyLayerNestedSt   -                                                                        ackUPDATE_COMPLETE                     AWS::CloudFormation::Stack          AwsSamAutoDependencyLayerNestedSt   -                                                                        ackUPDATE_IN_PROGRESS                  AWS::ApiGateway::RestApi            ServerlessRestApi                   -UPDATE_COMPLETE                     AWS::ApiGateway::RestApi            ServerlessRestApi                   -CREATE_IN_PROGRESS                  AWS::ApiGateway::Deployment         ServerlessRestApiDeployment8cf30e   -                                                                        d3cdUPDATE_IN_PROGRESS                  AWS::Lambda::Permission             HelloWorldFunctionHelloWorldPermi   Requested update requires the                                                                        ssionProd                           creation of a new physical                                                                                                            resource; hence creating one.UPDATE_IN_PROGRESS                  AWS::Lambda::Permission             HelloWorldFunctionHelloWorldPermi   Resource creation Initiated                                                                        ssionProdCREATE_IN_PROGRESS                  AWS::ApiGateway::Deployment         ServerlessRestApiDeployment8cf30e   Resource creation Initiated                                                                        d3cdCREATE_COMPLETE                     AWS::ApiGateway::Deployment         ServerlessRestApiDeployment8cf30e   -                                                                        d3cdUPDATE_IN_PROGRESS                  AWS::ApiGateway::Stage              ServerlessRestApiProdStage          -UPDATE_COMPLETE                     AWS::ApiGateway::Stage              ServerlessRestApiProdStage          -UPDATE_COMPLETE                     AWS::Lambda::Permission             HelloWorldFunctionHelloWorldPermi   -                                                                        ssionProdUPDATE_COMPLETE_CLEANUP_IN_PROGRE   AWS::CloudFormation::Stack          sam-app                             -SSDELETE_IN_PROGRESS                  AWS::Lambda::Permission             HelloWorldFunctionHelloWorldPermi   -                                                                        ssionProdDELETE_IN_PROGRESS                  AWS::ApiGateway::Deployment         ServerlessRestApiDeployment47fc2d   -                                                                        5f9dDELETE_COMPLETE                     AWS::ApiGateway::Deployment         ServerlessRestApiDeployment47fc2d   -                                                                        5f9dUPDATE_COMPLETE                     AWS::CloudFormation::Stack          AwsSamAutoDependencyLayerNestedSt   -                                                                        ackDELETE_COMPLETE                     AWS::Lambda::Permission             HelloWorldFunctionHelloWorldPermi   -                                                                        ssionProdUPDATE_COMPLETE                     AWS::CloudFormation::Stack          sam-app                             ----------------------------------------------------------------------------------------------------------------------------------------------CloudFormation outputs from deployed stack----------------------------------------------------------------------------------------------------------------------------------------------Outputs----------------------------------------------------------------------------------------------------------------------------------------------Key                 HelloWorldFunctionIamRoleDescription         Implicit IAM Role created for Hello World functionValue               arn:aws:iam::012345678910:role/sam-app-HelloWorldFunctionRole-BUFVMO2PJIYFKey                 HelloWorldApiDescription         API Gateway endpoint URL for Prod stage for Hello World functionValue               https://pcrx5gdaof.execute-api.us-west-2.amazonaws.com/Prod/hello/Key                 HelloWorldFunctionDescription         Hello World Lambda Function ARNValue               arn:aws:lambda:us-west-2:012345678910:function:sam-app-HelloWorldFunction-2PlN6TPTQoco----------------------------------------------------------------------------------------------------------------------------------------------Stack update succeeded. Sync infra completed.Infra sync completed.

Learn more

For a description of allsam sync options, seesam sync.

Thanks for letting us know we're doing a good job!

If you've got a moment, please tell us what we did right so we can do more of it.

Thanks for letting us know this page needs work. We're sorry we let you down.

If you've got a moment, please tell us how we can make the documentation better.