Serverless Framework Terminal Commands

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.

  1. Boilerplate
  2. Deployment and removal
  3. Information
  4. Logs
  5. Function invocations
  6. 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.