This article is adapted from my free online course The Serverless Framework: Quick Start.
One of the best features of The Serverless Framework is the command line interface (CLI) that comes built-in. The terminal commands I've found to be most helpful fall into six categories, the sixth of which is specific to a couple Serverless plugins that need to be installed separately.
- Boilerplate
- Deployment and removal
- Information
- Logs
- Function invocations
- Local development plugins
A Note On Shorthand
Many of the terminal commands have shorthand versions. For example, sls
is short for serverless
, -t
is short for --template
, etc. With the exception of serverless
which has no dashes, the long version of a command will have two dashes (--
) and the shorthand one (-
). For the most part, but not always, the short version is the first letter of the long version, so --template
can be shortened to -t
. Be careful, as this isn't always the case.
A Note Cloud Platforms
All of the terminal commands outlined here work for Amazon Web Services (AWS). Most of these commands should work with platforms other than AWS, but adjustments may be needed. See the serverless docs for more information.
I. Boilerplate
To create a Node.js (v. 6.10) project, use your terminal to navigate into the project folder and use the following command:
sls create -t aws-nodejs
To create the project folder and the boilerplate all at once, use this command (note that -p
is short for --path
:
sls create -t aws-nodejs -p your-project-name
To create a Node.js (v.6.10) project with Webpack installed and the latest ECMAScript features enabled:
sls create -t aws-nodejs-ecma-script
Serverless even gives you a TypeScript template!
sls create -t aws-nodejs-typescript
And, of course, AWS supports languages other than JavaScript. I personally love Python, and spin up my Python projects with this command:
sls create -t aws-python3
For a list of available templates for Amazon Web Services (AWS), check out this web page.
II. Deployment and removal
Deployment
Deploying to various stages (development, staging, qa, production, etc.) is a breeze with Serverless. Use the --stage
or -s
flag, and then the name of your stage. The command below will deploy to a dev stage.
sls deploy -s dev
If you have a default stage declared in your serverless.yml
file, then that's where your code will ship if you leave off the stage flag. For example, if your serverless.yml
file contains the snippet below (see line 4, in particular) then the command sls deploy
(no stage flag) will deploy to qa
.
provider:
name: aws
runtime: nodejs6.10
stage: qa
Removal
If you need to remove a project, use this command (make sure to specify a stage):
sls remove -s dev
If the functions in your project are deployed across several AWS regions and you only want to remove a function from one region, then specify the stage and the region.
sls remove -s dev -r us-east-1
The code above will remove all functions in the project from the dev
stage in the AWS region us-east-1
.
III. Information
If you ever forget, or lose, the information about your serverless project (API endpoints, function names, etc.), you can get all the data you need using the info
command. This code:
sls info -s dev
Will retrieve this information:
Service Information
service: my-serverless-service
stage: dev
region: us-east-1
api keys:
myKey: some123valid456api789key1011for1213api1415gateway
endpoints:
GET - https://dxaynpuzd4.execute-api.us-east-1.amazonaws.com/dev/users
functions:
my-serverless-service-dev-hello
You can get even more info if you add the -v
flag (short for --verbose
), like so: sls info -s dev -v
.
Service Information
service: my-serverless-service
stage: dev
region: us-east-1
api keys:
myKey: some123valid456api789key1011for1213api1415gateway
endpoints:
GET - https://dxaynpuzd4.execute-api.us-east-1.amazonaws.com/dev/users
functions:
my-serverless-service-dev-hello
Stack Outputs
CloudFrontUrl: d2d10e2tyk1pei.cloudfront.net
ScreenshotBucket: dev-svdgraaf-screenshots
ServiceEndpoint: https://12341jc801.execute-api.us-east-1.amazonaws.com/dev
ServerlessDeploymentBucketName: lambda-screenshots-dev-serverlessdeploymentbucket-15b7pkc04f98a
IV. Logs
To check the state of your functions, or investigate errors, you'll need access to your function's logs. The only required option is -f <function_name>
. If you don't use the -s
option for the stage, then the dev
stage is assumed.
sls logs -f my_function
The command below gets the logs for the function named my_function
, in the production stage, in the region us-west-2
sls logs -f my_function -s production -r us-west-2
If you only want the logs from the last five minutes, you can use the --startTime
option.
sls logs -f my_function --startTime 5m
Here's a list of other --startTime
abbreviations (taken directly from the docs).
30m # since 30 minutes ago
2h # since 2 hours ago
3d # since 3 days ago
Usually I want to see a live stream of my logs, which can be accomplished by using the -t
option.
sls logs -f my_function -t
V. Function invocations
Invoking your function is essential during development, but can also be useful for executing deployed functions on an as-needed basis.
When developing on your local machine, you can invoke a function named my_function
with this command:
sls invoke local -f my_function
If you need to pass it an argument, you can do so with the data option -d
. In the case below, the function is passed the string 'Hello!'.
sls invoke local -f my_function -d 'Hello!'
However, most of the time a function is passed a more complex data structure, like an object. You can invoke a function locally and pass it a JSON object as an argument like so:
sls invoke local -f my_function -d '{"productName": 'Thing', "price": 12.99, "discount": false}'
You can invoke the same function, with the same JSON data, but in a deployed stage by using the -s
flag and the desired stage.
sls invoke -s production -f my_function -d '{"productName": 'Thing', "price": 12.99, "discount": false}'
VI. Local development plugins
There are many community-built plugins that make The Serverless Framework even more pleasant to work with. You can find a list of plugins here.
The plugins I use most for development are serverless-offline
, and serverless-offline-scheduler
.
serverless-offline
When developing an API, serverless-offline
allows you to start a local version of your API and test it with curl
or Postman.
You can install it with npm install --save-dev serverless-offline
. Then in your serverless.yml
file, add it to a plugins
property (lines 6 & 7).
provider:
name: aws
runtime: nodejs6.10
stage: qa
plugins:
- serverless-offline
Once it's installed, in your terminal you can enter serverless offline start
, and your API will be served via localhost
. The default port is :3000
, but you can specify a different port with the --port
flag. For example, if you want serverless-offline
to use port 3333
, use the command serverless offline start --port 3333
.
For more information about the serverless-offline
API, see the docs.
serverless-offline-scheduler
For developing cron jobs locally, I use serverless-offline-scheduler
. You can install it with npm install --save-dev serverless-offline-scheduler
. Then in your serverless.yml
file, add it to a plugins
property (lines 6 & 7).
provider:
name: aws
runtime: nodejs6.10
stage: qa
plugins:
- serverless-offline-scheduler
To start serverless-offline-scheduler
, type serverless schedule
into your terminal. If you have a cron lambda, this will start a local cron server for you.