Getting Started
About Stencil
Transitioning to Stencil
Installing Stencil
Authentication & Tokens
Running Stencil Locally
Advanced Installation Options
Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars and Stencil
Handlebars.js Overview
Handlebars Helpers
Stencil Object Model
Stencil Objects

The Stencil CLI enables developers to locally develop and customize on any Stencil theme with no impact to a merchant’s live storefront during the development process. When developing locally, you will have access to real-time Browsersync preview and testing across desktop, mobile, and tablet devices/viewports. This article contains detailed instructions on installing Stencil CLI on Mac, Windows, and Linux.


You will need to have an authentication token to use the Stencil CLI. See Getting API Credentials in Authentication in our API Docs to learn how to obtain an API Token.

Each OS has different prerequisites. Be sure to check the correct tab in the Prerequisites by OS (Mac OS, Linux, or Windows) section before attempting installation.

Prerequisites by OS

Stencil Prerequisites by OS

Mac OS Prerequisites

Platform Support

These instructions have been tested on Mac OS X Yosemite. Dependencies for other platforms will be added upon further testing.

Installing Xcode

You must install the Xcode development tools (latest stable version).


Stencil requires the Node.js runtime environment, version 8.x.

We recommend that you install or update Node.js using nvm. First install nvm, version 0.31.0, as follows:

curl -o- | bash

Next, explicitly install a supported Node.js version, using this convention:

nvm install 8


If you run into any problems with Stencil installation or launch, please first see our Troubleshooting Your Setup page. Next, please consult our Support resources, which include community/peer support via BigCommerce Developer Community and Stack Overflow forums.

Install Stencil CLI

In your terminal (git bash recommended for Windows), use npm to install the Stencil CLI:

npm install -g @bigcommerce/stencil-cli

Items to Note

  • The command above requires npm to be installed in your local development environment.

  • In Windows, this npm command’s execution might at times appear to freeze. However, the installer is running. Give it several minutes to complete installation.

  • On Mac OS machines with installed xcode, version 5.x, this npm command has generated errors of the form: npm ERR! invalid: string_decoder. The workaround is to upgrade xcode to the latest stable xcode version (7.3.1 as of this page’s last revision).

  • If you receive a file-permissions error, and you did not install Node.js via nvm (Node Version Manager), then either install nvm now, or follow one of the workarounds on this external page.

CLI Force Upgrade and Cornerstone 2.0.0

To ensure the Stencil CLI is compatible with all the changes introduced in Cornerstone 2.0.0, you must upgrade to the latest version of Stencil CLI (1.15.1) if using Cornerstone 2.x.x.

Occasionally, you will receive a command line prompt to run the installation command when you restart your Stencil server. This occurs when BigCommerce publishes a critical fix in Stencil CLI, to resolve an issue like a newly discovered security exploit.

Cloning Cornerstone Repo

In your terminal, cd to the directory you would like to use for working on themes, then clone the cornerstone repo:

git clone git://

In the next step, we’ll install Stencil’s JavaScript utilities to enable API access via Ajax.

Back Up before Reinstalling

If you are reinstalling over a base theme on which you have already begun development, first back up your theme’s .stencil file. This contains your store URL, BigCommerce username and access tokens, and other basic settings. Preserving those settings will speed up initializing and launching the new version. If you would like to allow for complete rollback, back up your entire theme’s directory.

Installing Stencil CLI JS Dependencies

Before we can start using Stencil, we need to install some npm modules to leverage the Stencil event framework. To do so, cd into the cornerstone repo and run npm install:

cd cornerstone # move into cornerstone repo you just cloned

npm install # install dependencies with node package manager

Now that your installation is complete, you can move on to preparing your store/tokens

Video Demo

Watch a brief demonstration of the Stencil installation and launch: