AWS - Invoke

Invokes a deployed function. You can send event data, read logs and display other important information of the function invocation.

serverless invoke [local] --function functionName

Note: Please refer to this guide for event data passing when your function uses the http event with a Lambda Proxy integration.

Options

--function or -f The name of the function in your service that you want to invoke. Required.
--stage or -s The stage in your service you want to invoke your function in.
--region or -r The region in your stage that you want to invoke your function in.
--aws-profile The AWS profile you want to use.
--qualifier or -q The version number or alias to invoke. For a durable function the default is the alias its deploy publishes (durable, or the SnapStart or provisioned-concurrency alias when the function uses one); other functions are invoked unqualified ($LATEST).
--data or -d String data to be passed as an event to your function. By default data is read from standard input.
--raw Pass data as a raw string even if it is JSON. If not set, JSON data are parsed and passed as an object.
--path or -p The path to a json file with input data to be passed to the invoked function. This path is relative to the root directory of the service.
--contextPath, The path to a json file holding input context to be passed to the invoked function. This path is relative to the root directory of the service.
--context String data to be passed as a context to your function. Same like with --data, context included in --contextPath will overwrite the context you passed with --context flag.
--type or -t The type of invocation. Either RequestResponse, Event or DryRun. Default is RequestResponse.
--log or -l If set to true and invocation type is RequestResponse, it will output logging data of the invocation. Default is false.
--tenant-id The Tenant ID for the invocation.
--durable-execution-name Unique name for durable function execution (enables idempotency, 1-64 alphanumeric chars with hyphens/underscores).
--json Print one JSON object on stdout: statusCode, qualifier, executedVersion, durableExecutionArn, functionError, payload, log. Messages go to stderr.

For AWS Lambda MicroVMs (sandboxes), use --sandbox instead of --function. The framework starts a fresh MicroVM instance, sends the HTTP request through the AWS proxy, prints the response, and terminates the instance.

serverless invoke --sandbox <name> [--path /health] [--method POST] [--header 'Name: value'] [--data '{...}'] [--port 8080]

--sandbox The sandbox name as defined under sandboxes in serverless.yml. Required (cannot be combined with --function or --agent).
--path or -p HTTP request path. Default /.
--method HTTP method. Default GET.
--header A request header, as 'Name: value'. Repeat the flag for more headers. Values must be printable ASCII. It cannot set Host, X-Aws-Proxy-Auth or X-Aws-Proxy-Port, which the Framework sets to reach the sandbox.
--data or -d Request body (for non-GET requests).
--port Container port to send the request to. Default 8080.

The options for invoking a function or an agent (--qualifier, --type, --raw, --context, --contextPath, --tenant-id, --durable-execution-name, --session-id and --log) stop the command with an error, for example ✖ --qualifier is not available with --sandbox.

See the sandboxes guide for the caller IAM prerequisites and full details.

Invoking a web app

For web apps (AWS Lambda Web Functions), use --web-app instead of --function. The Framework sends one HTTP request to the web app's endpoint and prints the response: the status line and headers to standard error, then the body to standard output as it arrives, so piping the command to jq or a file passes the body alone. A redirect is printed, not followed. Requests to an aws_iam endpoint, or to a web app served on a custom domain, are signed with your AWS credentials.

serverless invoke --web-app <name> [--path /health] [--method POST] [--header 'Name: value'] [--data '{...}'] [--log]

--web-app The web app name as defined under webApps in serverless.yml. Required (cannot be combined with --function, --agent or --sandbox).
--path or -p HTTP request path. Default /.
--method HTTP method. Default GET.
--header A request header, as 'Name: value'. Repeat the flag for more headers, for example --method POST --header 'Content-Type: application/json' --data '{"a":1}'. A signed request is signed over these headers too. It cannot set Host, nor, for an aws_iam or custom-domain web app, Authorization, X-Amz-Date, X-Amz-Security-Token or X-Amz-Content-Sha256, which the Framework sets to sign the request.
--data or -d Request body. It is not sent with GET or HEAD, so set --method along with it.
--log or -l After the response, print the log lines of this request. Waits up to 30 seconds for them, then points to serverless logs --web-app <name>. Lines written outside a request (startup code, timers) or with process.stdout.write carry no request ID and are not shown.

The options for invoking a function, an agent or a sandbox (--qualifier, --type, --raw, --context, --contextPath, --tenant-id, --durable-execution-name, --session-id and --port) stop the command with an error, for example ✖ --qualifier is not available with --web-app.

$ serverless invoke --web-app api --path /health

HTTP 200 OK
content-length: 11
content-type: application/json; charset=utf-8
date: Thu, 15 Oct 2026 08:03:43 GMT
etag: W/"b-Ai2R8hgEarLmHKwesT1qcY913ys"
lambda-web-logstream: 2026/10/15/my-web-app-dev-api[rev-t8yf1]cc269a07c59a48d19d554992708bda83
lambda-web-request-id: DFWK6UW3VJPQRADPSKLN2OULWA
x-powered-by: Express

{"ok":true}

A response with status 400 or above is printed in full, and then the command exits with code 1 and the error ✖ Web app "api" returned HTTP 404..

The caller needs lambda:InvokeWebFunctionEndpoint for an aws_iam or custom-domain web app, and logs:FilterLogEvents on the web app's /aws/lambda/web/<function-name>.local log group for --log. See the web apps guide for details.

Provided lifecycle events

invoke:invoke

Invoke Local

Invokes a function locally for testing and logs the output. Keep in mind that we mock the context with simple mock data.

serverless invoke local --function functionName

Options

--function or -f The name of the function in your service that you want to invoke locally. Required.
--path or -p The path to a json file holding input data to be passed to the invoked function as the event. This path is relative to the root directory of the service.
--data or -d String data to be passed as an event to your function. Keep in mind that if you pass both --path and --data, the data included in the --path file will overwrite the data you passed with the --data flag.
--raw Pass data as a raw string even if it is JSON. If not set, JSON data are parsed and passed as an object.
--contextPath or -x, The path to a json file holding input context to be passed to the invoked function. This path is relative to the root directory of the service.
--context or -c, String data to be passed as a context to your function. Same like with --data, context included in --contextPath will overwrite the context you passed with --context flag.

Examples

AWS

serverless invoke --function functionName --stage dev --region us-east-1

This example will invoke your deployed function named functionName in region us-east-1 in stage dev. This will output the result of the invocation in your terminal.

Function invocation with data

serverless invoke --function functionName --data "hello world"

Function invocation with custom context

serverless invoke --function functionName --context "hello world"

Function invocation with context passing

serverless invoke --function functionName --contextPath lib/context.json

This example will pass the json context in the lib/context.json file (relative to the root of the service) while invoking the specified/deployed function.

Function invocation with data from standard input

node dataGenerator.js | serverless invoke --function functionName

Function invocation with logging

serverless invoke --function functionName --log

Just like the first example, but will also outputs logging information about your invocation.

Function invocation with data passing

serverless invoke --function functionName --path lib/data.json

This example will pass the json data in the lib/data.json file (relative to the root of the service) while invoking the specified/deployed function.

Example `data.json`

{
  "resource": "/",
  "path": "/",
  "httpMethod": "GET"
}

Function invocation with Tenant ID

serverless invoke --function functionName --tenant-id tenant-123

Durable functions

serverless invoke sends a durable function's invocation to the alias its deploy publishes, so it needs no --qualifier. With --type Event the command starts an execution and prints its ARN on stderr:

$ serverless invoke --function myDurableFunction --type Event --durable-execution-name order-1042

Durable execution started: arn:aws:lambda:us-east-1:123456789012:function:my-service-dev-myDurableFunction:4/durable-execution/order-1042/2f6c0d3e-8a41-4b7e-9c55-1d0e6a7b3f92

A synchronous invoke (the default RequestResponse type) waits for the execution to finish, prints Durable execution: <arn> on stderr, and prints the result on stdout. Lambda runs a durable function synchronously only when its durableConfig.executionTimeout is 900 seconds or less; for a longer timeout, the command stops with an error that suggests --type Event.

Add --json to read the ARN and the result from one JSON object on stdout (printed on one line; formatted here for reading):

serverless invoke --function myDurableFunction --type Event --durable-execution-name order-1042 --json

{
  "statusCode": 202,
  "qualifier": "durable",
  "executedVersion": null,
  "durableExecutionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-service-dev-myDurableFunction:4/durable-execution/order-1042/2f6c0d3e-8a41-4b7e-9c55-1d0e6a7b3f92",
  "functionError": null,
  "payload": null,
  "log": null
}

--durable-execution-name makes the invocation idempotent. With --type Event, a name that already exists returns that execution's ARN, even when the payload differs; the new payload is not used. A synchronous invoke with the same name and a different payload returns a DurableExecutionAlreadyStartedException error.

Local function invocation with custom context

serverless invoke local --function functionName --context "hello world"

Local function invocation with context passing

serverless invoke local --function functionName \
  --contextPath lib/context.json

This example will pass the json context in the lib/context.json file (relative to the root of the service) while invoking the specified/deployed function.

Limitations

Currently, invoke local only supports the Node.js, Python, Java and Ruby runtimes.

Resource permissions

Lambda functions assume an IAM role during execution: the framework creates this role, and set all the permission provided in the iam.role.statements section of serverless.yml.

Unless you explicitly state otherwise, every call to the AWS SDK inside the lambda function is made using this role (a temporary pair of key / secret is generated and set by AWS as environment variables, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY).

When you use serverless invoke local, the situation is quite different: the role isn't available (the function is executed on your local machine), so unless you set a different user directly in the code (or via a key pair of environment variables), the AWS SDK will use the default profile specified inside you AWS credential configuration file.

Take a look to the official AWS documentation (in this particular instance, for the javascript SDK, but should be similar for all SDKs):

Whatever approach you decide to implement, be aware: the set of permissions might be (and probably is) different, so you won't have an exact simulation of the real IAM policy in place.

AWS - Invoke

Invokes a deployed function. You can send event data, read logs and display other important information of the function invocation.

serverless invoke [local] --function functionName

Note: Please refer to this guide for event data passing when your function uses the http event with a Lambda Proxy integration.

Options

--function or -f The name of the function in your service that you want to invoke. Required.
--stage or -s The stage in your service you want to invoke your function in.
--region or -r The region in your stage that you want to invoke your function in.
--aws-profile The AWS profile you want to use.
--qualifier or -q The version number or alias to invoke. For a durable function the default is the alias its deploy publishes (durable, or the SnapStart or provisioned-concurrency alias when the function uses one); other functions are invoked unqualified ($LATEST).
--data or -d String data to be passed as an event to your function. By default data is read from standard input.
--raw Pass data as a raw string even if it is JSON. If not set, JSON data are parsed and passed as an object.
--path or -p The path to a json file with input data to be passed to the invoked function. This path is relative to the root directory of the service.
--contextPath, The path to a json file holding input context to be passed to the invoked function. This path is relative to the root directory of the service.
--context String data to be passed as a context to your function. Same like with --data, context included in --contextPath will overwrite the context you passed with --context flag.
--type or -t The type of invocation. Either RequestResponse, Event or DryRun. Default is RequestResponse.
--log or -l If set to true and invocation type is RequestResponse, it will output logging data of the invocation. Default is false.
--tenant-id The Tenant ID for the invocation.
--durable-execution-name Unique name for durable function execution (enables idempotency, 1-64 alphanumeric chars with hyphens/underscores).
--json Print one JSON object on stdout: statusCode, qualifier, executedVersion, durableExecutionArn, functionError, payload, log. Messages go to stderr.

Invoking a sandbox

serverless invoke --sandbox <name> [--path /health] [--method POST] [--header 'Name: value'] [--data '{...}'] [--port 8080]

--sandbox The sandbox name as defined under sandboxes in serverless.yml. Required (cannot be combined with --function or --agent).
--path or -p HTTP request path. Default /.
--method HTTP method. Default GET.
--header A request header, as 'Name: value'. Repeat the flag for more headers. Values must be printable ASCII. It cannot set Host, X-Aws-Proxy-Auth or X-Aws-Proxy-Port, which the Framework sets to reach the sandbox.
--data or -d Request body (for non-GET requests).
--port Container port to send the request to. Default 8080.

See the sandboxes guide for the caller IAM prerequisites and full details.

Invoking a web app

serverless invoke --web-app <name> [--path /health] [--method POST] [--header 'Name: value'] [--data '{...}'] [--log]

--web-app The web app name as defined under webApps in serverless.yml. Required (cannot be combined with --function, --agent or --sandbox).
--path or -p HTTP request path. Default /.
--method HTTP method. Default GET.
--header A request header, as 'Name: value'. Repeat the flag for more headers, for example --method POST --header 'Content-Type: application/json' --data '{"a":1}'. A signed request is signed over these headers too. It cannot set Host, nor, for an aws_iam or custom-domain web app, Authorization, X-Amz-Date, X-Amz-Security-Token or X-Amz-Content-Sha256, which the Framework sets to sign the request.
--data or -d Request body. It is not sent with GET or HEAD, so set --method along with it.
--log or -l After the response, print the log lines of this request. Waits up to 30 seconds for them, then points to serverless logs --web-app <name>. Lines written outside a request (startup code, timers) or with process.stdout.write carry no request ID and are not shown.

$ serverless invoke --web-app api --path /health

HTTP 200 OK
content-length: 11
content-type: application/json; charset=utf-8
date: Thu, 15 Oct 2026 08:03:43 GMT
etag: W/"b-Ai2R8hgEarLmHKwesT1qcY913ys"
lambda-web-logstream: 2026/10/15/my-web-app-dev-api[rev-t8yf1]cc269a07c59a48d19d554992708bda83
lambda-web-request-id: DFWK6UW3VJPQRADPSKLN2OULWA
x-powered-by: Express

{"ok":true}

A response with status 400 or above is printed in full, and then the command exits with code 1 and the error ✖ Web app "api" returned HTTP 404..

Provided lifecycle events

invoke:invoke

Invoke Local

Invokes a function locally for testing and logs the output. Keep in mind that we mock the context with simple mock data.

serverless invoke local --function functionName

Options

--function or -f The name of the function in your service that you want to invoke locally. Required.
--path or -p The path to a json file holding input data to be passed to the invoked function as the event. This path is relative to the root directory of the service.
--data or -d String data to be passed as an event to your function. Keep in mind that if you pass both --path and --data, the data included in the --path file will overwrite the data you passed with the --data flag.
--raw Pass data as a raw string even if it is JSON. If not set, JSON data are parsed and passed as an object.
--contextPath or -x, The path to a json file holding input context to be passed to the invoked function. This path is relative to the root directory of the service.
--context or -c, String data to be passed as a context to your function. Same like with --data, context included in --contextPath will overwrite the context you passed with --context flag.

Examples

AWS

serverless invoke --function functionName --stage dev --region us-east-1

This example will invoke your deployed function named functionName in region us-east-1 in stage dev. This will output the result of the invocation in your terminal.

Function invocation with data

serverless invoke --function functionName --data "hello world"

Function invocation with custom context

serverless invoke --function functionName --context "hello world"

Function invocation with context passing

serverless invoke --function functionName --contextPath lib/context.json

This example will pass the json context in the lib/context.json file (relative to the root of the service) while invoking the specified/deployed function.

Function invocation with data from standard input

node dataGenerator.js | serverless invoke --function functionName

Function invocation with logging

serverless invoke --function functionName --log

Just like the first example, but will also outputs logging information about your invocation.

Function invocation with data passing

serverless invoke --function functionName --path lib/data.json

This example will pass the json data in the lib/data.json file (relative to the root of the service) while invoking the specified/deployed function.

Example `data.json`

{
  "resource": "/",
  "path": "/",
  "httpMethod": "GET"
}

Function invocation with Tenant ID

serverless invoke --function functionName --tenant-id tenant-123

Durable functions

$ serverless invoke --function myDurableFunction --type Event --durable-execution-name order-1042

Durable execution started: arn:aws:lambda:us-east-1:123456789012:function:my-service-dev-myDurableFunction:4/durable-execution/order-1042/2f6c0d3e-8a41-4b7e-9c55-1d0e6a7b3f92

Add --json to read the ARN and the result from one JSON object on stdout (printed on one line; formatted here for reading):

serverless invoke --function myDurableFunction --type Event --durable-execution-name order-1042 --json

{
  "statusCode": 202,
  "qualifier": "durable",
  "executedVersion": null,
  "durableExecutionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-service-dev-myDurableFunction:4/durable-execution/order-1042/2f6c0d3e-8a41-4b7e-9c55-1d0e6a7b3f92",
  "functionError": null,
  "payload": null,
  "log": null
}

Local function invocation with custom context

serverless invoke local --function functionName --context "hello world"

Local function invocation with context passing

serverless invoke local --function functionName \
  --contextPath lib/context.json

This example will pass the json context in the lib/context.json file (relative to the root of the service) while invoking the specified/deployed function.

Limitations

Currently, invoke local only supports the Node.js, Python, Java and Ruby runtimes.

Resource permissions

Lambda functions assume an IAM role during execution: the framework creates this role, and set all the permission provided in the iam.role.statements section of serverless.yml.

Take a look to the official AWS documentation (in this particular instance, for the javascript SDK, but should be similar for all SDKs):

Whatever approach you decide to implement, be aware: the set of permissions might be (and probably is) different, so you won't have an exact simulation of the real IAM policy in place.

Serverless Framework

Serverless Framework