Stencil CLI Options and Commands
On This Page
Basic CLI Options and Commands
The syntax to run a basic Stencil CLI command is:
stencil <commands> [options] <parameter>.
To see the basic options and commands that the Stencil CLI package supports, enter any of the following forms of the help option on your command line:
stencil stencil help stencil --help stencil -h
Your terminal window will display options and commands listed in the tables below.
|-h, --help||Outputs usage information.|
|-V, --version||Outputs the version number (which is read from package.json file).|
|init||Interactively creates a .stencil file, which configures how to run a BigCommerce store locally.|
|start||Starts up the BigCommerce store, using theme files in the current directory.|
|bundle||Bundles up the theme into a structured .zip file, which can be uploaded to BigCommerce. (Please see restrictions here).|
|push||Bundles up the theme into a structured .zip file; then directly uploads (pushes) the .zip to BigCommerce.|
|release||Creates a new release in a theme's GitHub repository. Developers outside BigCommerce can use this for forks (not master) of Stencil's Cornerstone base theme, or for their own parallel themes independent of Cornerstone.|
|help <command>||display help and return all the options available to use for the specified command. For example,
Basic Stencil CLI Options and Commands
‘stencil start’ and ‘stencil push’ Options
stencil pushCLI Commands have additional custom options that can be used with the command, which are detailed below.
Stencil Start Options
To see Stencil CLI’s additional options for the
stencil start command (described above), enter the following on your command line:
stencil help start
Your terminal screen should read similar to the table below.
|-V, --version||Outputs the version number|
|-o, --open||Automatically open default browser|
|-v, --variation [name]||Set which theme variation to use while developing|
|--tunnel||Create a tunnel URL which points to your local server which anyone can use|
|-e, --theme-editor||Run Theme Editor server|
|-n, --no-cache||Turns off caching for API resource data per storefront page. The cache lasts for 5 minutes before automatically refreshing.|
|--theme-editor-port [port]||Run the Theme Editor on a different port|
|-h, --help||output usage information|
Stencil Push Options
To see Stencil CLI’s additional options for the stencil push command (described above), enter the following on your command line:
stencil help push
Your terminal screen should read similar to the table below.
|-V, --version||outputs the version number|
|--host [hostname]||specify the API host (default: https://api.bigcommerce.com)|
|-f, --file [filename]||specify the filename of the bundle to upload|
|-s, --save [filename]||specify the filename to save the bundle as|
|-a, --activate [variationname]||This will skip the prompts that normally come up asking if you would like to activate the theme and to specify a variation.
You can either specify the variation name after the flag or leave it blank to select the first variation (Light for Cornerstone).
|-h, --help||Output usage information.|
You can use the
--filename option in cases where you have already run
stencil bundle to bundle your theme, but the resulting .zip file has not yet been uploaded to BigCommerce. Use the generated .zip file’s filename as a parameter to identify the generated file in your theme directory. An example of the command is outlined below.
stencil push -f Cornerstone-2.3.2.zip
In this example,
Cornerstone-2.3.2.zip is the name of the file that was generated after running
When you run
stencil push with the
--filename option, Stencil CLI skips all its bundling steps and diagnostics. It proceeds directly to uploading the specified file, displaying its processing progress bar to show upload status.
Theme Editor Local Launch Quick Reference
|Launch type||Command||Theme Port URL||Theme Editor Port URL|
||http://localhost:3000 (or custom port)||N/A|
|Theme, Theme Editor||
||http://localhost:3000 (or custom port)||http://localhost:8181|
|Theme and Theme Editor||
||http://localhost:3000 (or custom port)||http://localhost:9000 (#### = custom port)|
Local Launch: Theme Only
After initializing Stencil, issue the following command in your theme directory (Windows users need to run this in git bash):
When you navigate to your designated port (e.g http://localhost:3000), you should see the storefront you selected with the local Stencil theme applied.
Troubleshooting Token Error
If you receive the following error message,
Unauthorized, please use a valid username/token, then store token authentication has failed. In this case, please evisit Authorizing and Initializing the Stencil CLI.
Local Launch: Theme and Theme Editor
If you want to view or reconfigure the Theme Editor/Store Design settings, you can run Stencil locally while also launching a local version of Theme Editor. This will help you see the UX changes that result from editing the
To run Stencil locally while also launching a local version of Theme Editor, start in your theme directory and run the same command as above (
stencil start), but append the
stencil start -e
The Theme Editor server will run in parallel with the stencil theme at https://localhost:8181.
Customizing Theme Editor’s Port
You can override Theme Editor’s default port by appending the “–theme-editor-port [port]” option. For example, to specify port
9000, you would enter:
stencil start -e --theme-editor-port 9000
To verify Theme Editor’s launch, you would then go to https://localhost:9000. Using this option, you can specify any port between
Local Launch: Disabling Caching
By default, Stencil caches API resource data per storefront page. This minimizes server traffic while you develop your theme locally.
If you prefer to see your changes reflected immediately in your live store, you can turn off caching by appending the
stencil start --no-cache
stencil start -n
To re-enable caching:
Kill the current Stencil server (ctrl + c will do the job) and restart Stencil, this time omitting the