Image for post
Image for post

Meet AWS SAM CLI: sam init

Welcome to the first installment of “Meet AWS SAM CLI”. In this series I will provide simple instructions on the most common use cases of AWS SAM CLI and how it can help you as a developer move faster and be more efficient in your development process.

The AWS SAM CLI is a command line tool that operates on an AWS SAM template and application code. With the AWS SAM CLI:

  • Initialize a serverless application from a template.
  • Invoke and debug a Lambda function locally.
  • Create a deployment package for your serverless application.
  • Deploy your serverless application to the AWS cloud.

To install the SAM CLI please refer to For this post I will be using SAM CLI v0.18.0.

The init command

The first command I am going to look at is “sam init”. To get started, let’s run the basic init command and see what happens:

SAM CLI will set up a basic serverless “hello-world” application under a folder called sam-app. This application consists of the following structure and defaults to a runtime of node.js v8.10.

While this might be enough to get started, SAM CLI can do much more to help you create the perfect starting point for your serverless application. To discover more, let’s run the init command again but this time with the help flag.

This command will output a description of the Usage, Common usage, and Options available. I am going to skip the Common usage examples for now and cover them a bit further down. For now, take a look at the Usage and Options. For the Usage, the following is displayed.

“Initialize a serverless application with a SAM template, folder structure for your Lambda functions, connected to an event source such as APIs, S3 Buckets or DynamoDB Tables. This application includes everything you need to get started with serverless and eventually grow into a production scale application.

This command can initialize a boilerplate serverless app. If you want to create your own template as well as use a custom location please take a look at our official documentation.”

For the Options, the following items are displayed.

Possible Values: TEXT

Description: Template location (git, mercurial, http(s), zip, path).

Possible Values: nodejs , nodejs6.10, nodejs8.10, nodejs10.x, dotnet, dotnetcore, dotnetcore1.0, dotnetcore2.0, dotnetcore2.1, go, go1.x, python, python2.7, python3.6, python3.7, java, java, ruby, ruby2.5

Description: Lambda Runtime of your app.

Possible Values: npm, pip, bundler, cli-package, maven gradle

Description: Dependency manager of your Lambda runtime.

Possible Values: PATH

Description: Where to output the initialized app into.

Possible Values: TEXT

Description: Name of your project to be generated as a folder.

Description: Disable prompting and accept default values defined template config.

Description: Turn on debug logging to print debug message generated by SAM CLI.

Description: Show this message and exit.

Options explained

Some of these options are self-explanatory, however, I want to dig in a bit and see if I can surprise you with some SAM capabilities you might be unaware of.

The runtime option

With the runtime option I can tell SAM CLI to generate an application template in my preferred programming runtime. As for runtime families, I have Node, Dotnet, Go, Python, Java, and Ruby. Additionally, you can see version options in each of the runtimes as well. There are some generics for each family of runtimes, as well as some specifics. I have listed the runtimes again with a legend to show which are default and which I have to call specifically.

While nodejs8.10 is the default if you do not pass a runtime to init, each of the languages also has a default. For example, passing dotnet, dotenetcore will default to dotnetcore2.1.

The dependency-manager option

I might not use the dependency-manager option all the time, but comes in handy when I want to choose a different dependency-manager for my serverless application that is not the default. For example, if I am building a serverless application with the Java runtime I would use the following command:

The simple application structure that is generated looks like this:

Notice the pom.xml file in the root of the HelloWorldFunction. This file is used by the Maven to handle dependencies for a Java application. Therefore, I now know that Maven is the default dependency-manager for Java. Let’s say I want to use Gradle to manage my application dependencies instead:

Now when I look at my application structure, I see it has changed.

Instead of the pom.xml file, I see several Gradle files that allow me to use Gradle as a dependency manager.

Again, this is not an option I will use much as I am generally a Node.js developer. However, it offers a great deal of flexibility when my language of choice might have more than one dependency manager.

The output-directory option

This option comes in handy if I need to create an app in a location other than the current directory. For example, I have a directory called project1 that is empty. I can run the following command:

After this, I get the following structure:

I now have an application that exists in the project1 directory. However, I also notice that it is under a folder called sam-app. This is the default application name given to all applications by the SAM CLI. In the name option we will look at how to change that.

The name option

This option allows me to name the application. The name I choose will be the name of the directory containing the application as well as in the description in the template.yaml file.

This will render the following structure.

Also, the template.yaml file will have the following entry.

Now I want to re-run my command from the output option section.

And now I have this.

Using the output-dir and name options, I can now specify the output location and the name of the application folder.

The location option

This option is probably one of the biggest surprises in the SAM CLI as it is useful and somewhat misunderstood. This option is helpful when creating new applications as well as when modifying current applications. I want to break this into two parts to help explain more clearly.

Creating a new application
As we have seen before, we can use sam init to create new applications from templates that are managed by AWS. However, it is also possible for me to create my own templates as starters for applications. I am going to create a basic application to use an example.

Here is the resulting template structure.

I also want to take a look at the template.yaml file to see what the AWS managed application template looks like.

There is a lot of helpful information in here. However, I am pretty familiar with the template and I don’t need all the comments. There are also a few changes I make in the template every time I create a new application.

Here is an example of a basic, single-function template that I like to start with.

Some key changes are:

  1. I removed the comments.
  2. I added a Mappings to load a common layer I use in my Node development (AWS SDK, X-Ray).
  3. Moved many of the function parameters into the Globals area.
  4. Renamed the function to be more applicable to my needs.
  5. Removed some of the outputs that I do not care about.

In addition to the changes to the template.yaml file, I also updated the directory structure according to the references in the template, modified the to reflect the relevant changes, and removed some files that I do not use. I can continue to make these changes manually every time I create a new application, or I can take advantage of the location option in SAM CLI.

In order to make the templates usable by SAM CLI, they must be formatted in the cookiecutter configuration. Cookiecutter is a CLI that allows you to create projects from templates. As a developer, I can setup a common file structure, dependencies, language, and other settings to use as a starting point for my projects. See for more information on cookiecutter.

Using the cookiecutter format, I have built a template based on my changes that I will demonstrate as an example. My template can be found at In the cookiecutter template, my directory structure looks like this:

To make use of this template I can use the location option:

When prompted for a project_name, I will enter “My New App”. For the project_slug I will enter “my-new-app” which should also be the default value. The resulting directory structure looks like this:

I now see that my project has been created from everything in the {{cookiecutter.project_slug}} directory from above. And the folder has been named from my project_slug value. I now look inside my new template.yaml file and it looks like this.

Now I have a simple starting point for all my Node.js applications that have the starting file structure I want and the included Lambda layers that I need.

Modifying a current application

Not only can I create a new application from a cookiecutter template, I can also add a cookiecutter template to an existing application. A great example of this is the “Cookiecutter Pipeline for SAM based Serverless Apps” which can be found at

With this template I can, very simply, add a continuous integration and continuous delivery (CI/CD) pipeline to my current application I just created. From the root of the my-new-app directory, I am going to run the following.

When I run this, I will be prompted for a new project name and asked to select between GitHub and CodeCommit. I entered the project cicd and selected GitHub as my repository. After completing these steps, I will examine the directory structure of my application for changes.

I notice that four new files have been added to my application:

  1. instructions on deploying the new CICD pipeline.
  2. buildspec.yml: the build commands for the pipeline to run when building my application.
  3. pipeline-sample.png: a graphical representation of my new CICD pipeline.
  4. pipeline.yaml: the infrastructure for my new CICD pipeline stored as code.

To enable the CI/CD pipeline, all I need to do is follow the instructions in the file. This involves setting a few parameters and creating the CloudFormation stack. If you are interested in more on the CI/CD cookiecutter template and how to use it, please refer to this Start Right video.

That’s it! By using the location option, I was able to create a new application from my own custom template and add a CI/CD from an aws-sample cookiecutter template. Using the cookiecutter configuration you can build your own starter templates as well.

What locations can I use?
Before I move on, I want to talk about the locations that are valid for this option. In my example I used GitHub, but it is also possible to use local files or folders, and online files. When formatting my location string, it is important to note that Cookiecutter knows abbreviations for GitHub (gh), Bitbucket (bb), and GitLab (gl) projects, but you can also give it the full URL to any repository.


BitBucket (git or mercurial (hg))

Local zip file

Remote zip file

Local folder

To learn more about location options, refer back to the sam init — help in the terminal and read the usage section, or get a full explanation from the CookieCutter documentation.

The no-input option

This option directly relates to the location option. When calling a cookiecutter template, the author of the template will have defaults for prompted values. If I pass the –no-input flag to sam init, then the defaults will be used without prompting for values.

The debug option

Passing the –debug flag to sam init will cause SAM CLI to output debug information pertaining to the CLI itself and not my application.

The help option

Passing the –help flag to sam init will display the help message we generated at the beginning of this post.


AWS SAM CLI is designed to help developers move quickly and efficiently in serverless application development and sam init is where it all starts. Using options for runtime, name, and location allows me to quickly create a starting point for my application without having to manually build from scratch. I can get even more specific to my preferences by using cookiecutter templates. Hopefully, you have seen how SAM CLI can get you up and running quickly and efficiently with sam init in the SAM CLI, and are ready to start coding more efficiently with SAM!

Happy coding!

Background image credit: Gerd Altmann from Pixabay

Written by

Christian, husband, dad of 5, musician, Senior Developer Advocate — Serverless for @AWScloud . Opinions are my own. #Serverless #ServerlessForEveryone

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store