Stencil CLI Options and Commands

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.

Option Description
-h, --help Outputs usage information.
-V, --version Outputs the version number (which is read from package.json file).

Command Description
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, stencil help bundle will return the options that are available to use specifically with the stencil bundle command.

Basic Stencil CLI Options and Commands

#### Basic Stencil CLI Options and Commands

‘stencil start’ and ‘stencil push’ Options

The stencil start and stencil push CLI 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.

Option Definition
-V, --version Outputs the version number
-o, --open Automatically open default browser
-v, --variation [name] Set which theme variation to use while developing
-t, --test Enable QA mode which will bundle all javascript for speed to test locally
--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.

Option Definition
-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 -f or --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 stencil bundle.

When you run stencil push with the -f or --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
Theme Only stencil start http://localhost:3000 (or custom port) N/A
Theme, Theme Editor stencil start -e http://localhost:3000 (or custom port) http://localhost:8181
Theme and Theme Editor stencil start -e --theme- editor-port 9000 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):

stencil start

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 schema.json file.

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 -e option:

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 1024 and 65535.


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 --no-cache or -n option:

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 --no-cache or -n option.

stencil start


Resources

Related Articles