sam local start-api - AWS Serverless Application Model (original) (raw)

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) sam local start-api subcommand.

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

Usage

$ sam local start-api <options>

Options

--add-host `LIST`

Passes a hostname to IP address mapping to the Docker container's host file. This parameter can be passed multiple times.

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

--beta-features | --no-beta-features

Allow or deny beta features.

--config-env `TEXT`

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.

--config-file `PATH`

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.

--container-env-vars

Optional. Pass environment variables to image container when locally debugging.

--container-host `TEXT`

Host of locally emulated Lambda container. The default value islocalhost. 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`

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

Turns on debug logging to print debug message generated by the AWS SAM CLI and display timestamps.

--debug-args `TEXT`

Additional arguments to be passed to the debugger.

--debug-function

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`

When specified, starts the Lambda function container in debug mode and exposes this port on the local host.

`` --debugger-path `TEXT` ``

The host path to a debugger that will be mounted into the Lambda container.

--docker-network `TEXT`

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`

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`

The JSON file that contains values for the Lambda function's environment variables.

--force-image-build

Specifies whether AWS SAM CLI should rebuild the image used for invoking functions with layers.

--help

Shows this message and exits.

--hook-name `TEXT`

The name of the hook that is used to extend AWS SAM CLI functionality.

Accepted values: terraform.

--host `TEXT`

The local hostname or IP address to bind to (default: '127.0.0.1').

--invoke-image `TEXT`

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`

Specifies the location basedir where the Layers your template uses are downloaded to.

--log-file, -l `TEXT`

The log file to send runtime logs to.

--no-memory-limit

Removes the memory limitation in the container during local invoke, even when memory is configured in the AWS SAM template.

--parameter-overrides

A string that contains AWS 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:

--port, -p `INTEGER`

The local port number to listen on (default: '3000').

--profile `TEXT`

The specific profile from your credential file that gets AWS credentials.

--region `TEXT`

The AWS Region to deploy to. For example, us-east-1.

--save-params

Save the parameters that you provide at the command line to the AWS SAM configuration file.

--shutdown

Emulates a shutdown event after the invoke completes, in order to test extension handling of shutdown behavior.

--skip-prepare-infra

Skips the preparation stage if no infrastructure changes have been made. Use with the --hook-name option.

--skip-pull-image

Specifies whether the CLI should skip pulling down the latest Docker image for the Lambda runtime.

--ssl-cert-file `PATH`

Path to SSL certificate file (default: None). When using this option, the --ssl-key-file option must also be used.

--ssl-key-file `PATH`

Path to SSL key file (default: None). When using this option, the --ssl-cert-file option must also be used.

--static-dir, -s `TEXT`

Any static asset (for example, CSS/JavaScript/HTML) files located in this directory are presented at /.

--template, -t `PATH`

The AWS SAM template file.

Note

If you specify this option, AWS SAM loads only the template and the local resources that it points to.

--terraform-plan-file

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]`

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

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