AWS SAM CLI: build, run and deploy Lambda functions from one command line

The gap AWS SAM CLI fills for Lambda developers

Writing a Lambda function is easy. Getting it from a source directory to a running function with the right layers, environment variables, IAM policy and event source is not, and doing that repeatedly during development is worse. The AWS SAM CLI exists to close that loop. The README describes it as an open-source CLI tool that helps you develop serverless applications containing Lambda functions, Step Functions, API Gateway, EventBridge, SQS, SNS and more.

The audience is narrow and specific: developers who have already decided their application runs on AWS serverless primitives. If your compute target is a Kubernetes cluster or a long-running container, the tool has nothing to offer you. If your application is a set of Lambda functions behind API Gateway, the sam init, sam build, sam local and sam deploy commands cover the whole path from an empty directory to a deployed stack.

The tool is not a general AWS CLI replacement, and that distinction comes up often enough to be worth stating plainly. The AWS CLI manages arbitrary AWS resources. The SAM CLI reads a SAM template, resolves it through the SAM transform into CloudFormation, and then builds and deploys that. Every command is scoped to an application, not to an account.

How sam build, sam local and sam deploy move your code

The mechanism is a pipeline with four stages, and knowing which stage owns a failure saves a lot of time.

The template is the input. It is written in SAM shorthand, which the aws-sam-translator package converts into full CloudFormation. That translator is pinned in pyproject.toml at an exact version, which means template syntax support moves only when the CLI dependency moves.

The build stage is delegated. sam build does not compile your function itself. It calls aws-lambda-builders, also pinned to an exact version, which knows how to prepare each supported runtime. For functions that do not fit a supported runtime, the README points to custom Makefile workflows. That is the escape hatch, and it is the one most teams end up using when their dependency layout is unusual.

The local stage uses Docker. The README states that sam local commands run a Lambda-like execution environment in a Docker container, and that they work on SAM and CDK applications. This is why Docker is a practical prerequisite for local testing rather than an optional extra.

The deploy stage hands off to CloudFormation. sam deploy takes the built artifacts and the translated template and creates or updates a stack. sam sync is the faster loop for developer environments, pushing changes to the cloud without a full stack update. sam pipeline init generates CI/CD pipeline configuration from prebuilt templates, and sam logs and sam traces read CloudWatch Logs and X-Ray. The CLI is the front end; CloudFormation is the state holder.

Installing AWS SAM CLI and running a first local function

The README does not inline installation steps. It links to the AWS installation page and shows two package badges, brew with aws/tap/aws-sam-cli and pip with aws-sam-cli. Those two names are the ones to use.

On macOS with Homebrew, the tap and formula come straight from the badge:

brew tap aws/tap
brew install aws-sam-cli

On Linux or Windows, the pip route installs the same package. The project metadata in pyproject.toml declares requires-python >=3.10, so check your interpreter before installing:

pip install aws-sam-cli

The repository publishes releases on a regular cadence, with v1.166.2 dated 2026-09-11 and v1.166.1 dated 2026-09-04, plus nightly builds such as v1.166.2.dev202609210901 dated 2026-09-21. The Makefile in the repository shows how the project itself pulls a binary for testing, with targets named init-nightly and init-latest-release that call tests/install-sam-cli-binary.sh, but those are maintainer targets rather than an end-user install path.

From there, the README points to sam init for scaffolding and to the Hello World quick start for the full walkthrough. sam init pulls from the aws-sam-cli-app-templates repository, so the templates you get are separate from the CLI release you installed. The README lists the commands that make up the loop: sam init, sam build, sam local, sam sync, sam deploy, sam pipeline init, sam logs and sam traces. sam local invoke needs Docker running. The README does not document rollback behaviour for a failed deploy.

Where AWS SAM CLI gets in your way

The build step is the sharpest constraint. Because sam build delegates to aws-lambda-builders at a pinned version, your function's dependency model has to fit what that library supports. Native dependencies, vendored binaries or a build system it does not recognise push you into the custom Makefile workflow, at which point you are maintaining build logic yourself and the convenience argument weakens considerably.

Docker is a hard dependency for local testing, not a soft one. sam local commands run your function in a container. On a locked-down workstation or a CI runner without a Docker daemon, the local half of the tool is unavailable, and you are left with build and deploy only.

The dependency pins are aggressive by design. pyproject.toml pins click to 8.1.8, boto3 to 1.43.83, aws-sam-translator to 1.113.0 and aws_lambda_builders to 1.67.0, and the file carries a comment that docker minor version updates can include breaking changes, so only the micro version auto-updates. If you install the CLI into a shared virtualenv alongside other tools, those exact pins can conflict, and the resolution is usually to install it in its own environment or use the standalone installer.

Finally, the tool is AWS-only by construction. It translates a SAM template into CloudFormation. There is no path to another cloud, and no meaningful local emulation of services beyond what the Docker container provides.

AWS SAM CLI against Terraform and the AWS CDK

The honest comparison is not with the AWS CLI, which solves a different problem, but with the other two ways people define Lambda infrastructure.

Terraform takes the opposite approach to state. Your configuration describes resources, and Terraform keeps a state file that it reconciles against the real account. SAM CLI keeps no state of its own; CloudFormation holds the stack, and the CLI is a client of it. That means a SAM deployment shows up in the CloudFormation console as an ordinary stack, which matters if your organisation already governs AWS through CloudFormation StackSets and drift detection. It also means you inherit CloudFormation's update semantics, including the cases where an update requires resource replacement.

The AWS CDK is closer in spirit but inverts the authoring model. You write TypeScript, Python or Java that synthesises CloudFormation, rather than writing a template directly. The README notes that sam local commands work on CDK applications, so the two are not mutually exclusive: teams that prefer imperative infrastructure code can still use the CLI for local invocation and log tailing. The difference is where the abstraction lives. CDK puts it in a programming language; SAM puts it in template shorthand that the translator expands.

A practical rule: if your team already writes CloudFormation and wants less of it, SAM is the smaller step. If your team wants a general-purpose language and constructs, CDK is the larger one.

Licence, release cadence and the cost of upgrading

The project is licensed Apache-2.0, declared in pyproject.toml and present as a LICENSE file at the repository root. There is also a NOTICE file and a THIRD-PARTY-LICENSES file, which is what you would expect from a project with this many pinned dependencies. Apache-2.0 includes a patent grant and requires attribution for redistributed copies. If you vendor the CLI into an internal distribution, read the NOTICE and THIRD-PARTY-LICENSES files before you ship. That is a description of the files present, not legal advice.

Upgrade cost is real but bounded. Releases arrive frequently, with v1.166.1 and v1.166.2 landing within a week of each other in September 2026, and nightly builds published on the develop branch. The pinned dependencies mean an upgrade can shift the SAM transform behaviour, the set of supported runtimes and the Docker client version in one step. If your template relies on recently added syntax, check the aws-sam-translator version in the release you are moving to against the one you are on.

The repository is not archived and the last push was on 2026-09-21. Development happens on the develop branch, so the default branch you see is ahead of the released versions. For a fork or a patch, that is the branch to track.

Editorial conclusion

Adopt AWS SAM CLI if your functions run on AWS Lambda and you want the same template to drive local Docker testing and CloudFormation deployment. Do not adopt it if your compute target is not AWS, or if you need a runtime that aws-lambda-builders does not support, because the build step is the part you cannot work around. Before committing, verify that the Python version on your build machine satisfies requires-python >=3.10, check that the pinned aws-sam-translator version in pyproject.toml matches the SAM template syntax you intend to use, and confirm Docker is available if you plan to run sam local. The repository was last pushed on 2026-09-21 and is not archived, so the develop branch is the moving target you would be tracking.

Frequently asked questions

Official sources

1. aws/aws-sam-cli on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases