A useful AWS SAM CLI workflow keeps code feedback local until you need to check AWS service behavior. Build the application when its generated artifacts or dependencies change, invoke a function with a deliberate test event, and use a deployed development stack to verify cloud integrations.

This guide assumes you already have a SAM project. If you need the initial tools and project configuration, see the AWS SAM Local setup guide.

Choose the local command that matches the change

sam build prepares function code and dependencies for later local testing or deployment. It writes build artifacts under .aws-sam. Run it when you change dependencies, build configuration, or code that SAM runs from those artifacts:

sam build

Then use sam local invoke for one function call, or sam local start-api when you need to exercise an HTTP route declared in the template. These commands run function code locally in a Lambda-like container. The SAM build guide explains how build artifacts feed local testing; the local invoke guide covers function invocation.

When a project has a built .aws-sam directory, rebuild after source changes so local commands use the updated artifact. Edit the original project files, not generated files under .aws-sam/build. If you are unsure which template or artifact SAM selected, pass --template explicitly or inspect the command output.

Invoke one function with a saved event

Keep representative inputs in version control so a test is easy to repeat. For a one-off invocation, pass the function's logical ID and an event file:

sam local invoke OrdersFunction --event events/order-created.json

For an HTTP function, start the local API and call the method and path declared in your SAM template:

sam local start-api
curl http://127.0.0.1:3000/orders

The local server uses port 3000 by default; set another port with --port if it conflicts with another service. Local API testing exercises the function through SAM's local HTTP server, not a deployed API Gateway endpoint.

Make event and environment inputs repeatable

You can create an event payload by hand or start with a sample from sam local generate-event. For example, save an S3 put event in your project's events directory for a function whose handler accepts that event shape. Create the directory if it does not exist. The function logical ID here is illustrative:

sam local generate-event s3 put > events/s3-put.json
sam local invoke S3EventFunction --event events/s3-put.json

Review and edit generated samples to match the cases your handler must support. A sample event supplies input to one local function invocation; it does not upload an object, run an S3 notification, or verify that the deployed trigger is configured. See AWS's guide to generating and testing event payloads.

Declare variables such as STAGE and TABLE_NAME under the function's Environment.Variables in the template, then use --env-vars to supply local override values. In the JSON file, the top-level Parameters object applies overrides to all functions, while a function-specific entry takes precedence. See AWS's environment variable file guide.

{
  "Parameters": {
    "STAGE": "local",
    "TABLE_NAME": "orders-local"
  },
  "OrdersFunction": {
    "TABLE_NAME": "orders-test"
  }
}

sam local invoke OrdersFunction --event events/order-created.json --env-vars env.local.json

In this example, the function-specific table name overrides the global value. Use local or sandbox resource names, keep credentials out of committed event and environment files, and add any sensitive local file to .gitignore. If the function calls real AWS APIs during a local run, it can use credentials available to your local process; that does not test the Lambda execution role. Use an appropriately scoped development profile and verify the deployed role in AWS.

Reduce repeated setup in the feedback loop

Reuse local function containers

For repeated calls through the local API, ask SAM to keep function containers between invocations:

sam local start-api --warm-containers lazy

lazy starts a function container on its first request and reuses it afterward. eager starts containers for all functions when the API starts. This reduces repeated container setup during local testing; it does not measure Lambda cold starts or guarantee production performance. When you edit code in a built project, run sam build before invoking the updated artifact again. AWS documents these options in its local API testing guide.

Use build caching where dependencies are stable

sam build --cached reuses artifacts for resources SAM identifies as unchanged:

sam build --cached

This can help when builds repeatedly install or assemble the same dependencies. SAM does not detect newer versions of unpinned third-party dependencies during a cached build, so use sam build --no-cached when you need to resolve them again or diagnose stale output. The explicit flag also overrides cached-build settings in samconfig.toml. For packages with native components that need to match the Lambda build environment, use sam build --use-container; container builds take additional setup and image-pull time. See AWS's build options and caching reference.

Debug the local invocation

Attach an IDE debugger

Start a function in debug mode by exposing a debugger port. Configure your IDE's attach settings for the function's language runtime, then set breakpoints and attach to that port:

sam local invoke -d 5858 --event events/order-created.json OrdersFunction

The debugger protocol and IDE configuration depend on the runtime. With sam local start-api, a single debug port can be used for one function at a time; send a request to that function to start it before attaching. AWS's local debugging guide lists the supported approaches and options.

Separate local output from AWS logs

During a local invocation, inspect the function output and SAM CLI messages in the terminal where you ran the command. Add structured, useful application logs around inputs, decisions, and errors, while avoiding secrets and sensitive payload data.

With sam local invoke, the function's returned result goes to stdout and runtime logs go to stderr. sam logs reads logs for a deployed Lambda function from CloudWatch Logs; it is not a viewer for local invocation output. For example, to follow a function in a development stack:

sam logs -n OrdersFunction --stack-name sam-app-dev --tail

This requires AWS access to the stack's logs. The SAM logging guide documents filtering and time-range options.

Know what local tests cannot prove

A local invocation is valuable for checking handler logic against chosen inputs, but it does not reproduce the full AWS account and service environment. A passing event-file test does not prove that a deployed event source invokes the function, that its execution role has the right permissions, or that cloud networking, quotas, and managed-service behavior match the local run. AWS describes these gaps in its Lambda testing guide.

Use local runs for fast code feedback, then test the integrated path in a development environment when a change depends on AWS resources or permissions. Prefer a small, repeatable cloud test with non-production data to relying on a local event payload for that check.

Use SAM sync for a development stack

When a local test is not enough, sam sync --watch watches the project and syncs changes to AWS. It compares the local template with the deployed stack and performs an initial CloudFormation deployment when it detects a change; otherwise the default --skip-deploy-sync behavior can skip that step. As files change, SAM uses service APIs for supported code updates and CloudFormation for infrastructure changes. See the current sam sync command reference for these options.

sam sync --stack-name sam-app-dev --watch

This is a cloud development loop: it needs AWS credentials, changes an AWS stack, and can incur service costs. Code updates sent through AWS service APIs can cause CloudFormation drift, so point this command only at a development stack. AWS recommends sam sync for development environments and sam deploy or a CI/CD pipeline for production; see the SAM sync guide. For a separate release workflow, continue with the AWS SAM Pipelines setup guide.

A practical daily sequence is: make the change, rebuild when generated artifacts or dependencies need updating, invoke the function with a saved event or exercise its local route, and use a development stack to verify AWS behavior that local tests cannot establish.