> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Stencil CLI Options and Commands This article is a comprehensive command reference for Stencil CLI, BigCommerce's powerful theme development and deployment tool. For installation instructions for your OS, see [Installing Stencil CLI](/developer/docs/storefront/stencil/cli/install). For more information on BigCommerce's Stencil Theme Engine, see [About Stencil](/developer/docs/storefront/stencil/getting-started). Continue reading below for detailed information on each Stencil CLI command and option. > **Note** > > BigCommerce is currently sunsetting its node-sass fork in favor of the latest [sass/node-sass](https://github.com/sass/node-sass). To ensure that your storefront is up to date, use the latest active or maintenance node version in Stencil CLI and use the CLI command to resolve [incompatible SCSS directives](/developer/docs/storefront/stencil/cli/unexpected-behavior#incompatible-scss-directives), which can cause issues with the styling of your storefront. Your current production site will continue to function as designed, but all future updates will require you to address any SCSS compatibility issues with Node.js 20. This upgrade is necessary to ensure the security of our platform and that you are not running out-of-date packages that may expose your projects to additional security vulnerabilities. ## Commands overview The syntax to run a Stencil CLI command is as follows: **`Stencil CLI command syntax`** ```shell title="Stencil CLI command syntax" showLineNumbers={false} stencil COMMANDS [OPTIONS] ``` Running `stencil help` outputs a full list of commands and their descriptions. For more detailed information and usage examples, click a link in the table below: | Command | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [init](#stencil-init) | Interactively creates a `.stencil` file or `secrets.stencil.json` and `config.stencil.json` files (if using Stencil V3.1 release or later), which configures how to run a BigCommerce store locally. | | [start](#stencil-start) | Starts up the BigCommerce storefront local development environment, using theme files in the current directory and data from the live store. | | [bundle](#stencil-bundle) | Bundles up the theme into a structured `.zip` file, which can be uploaded to BigCommerce. | | [pull](#stencil-pull) | Pulls the configuration from the active theme on your live store and updates your local configuration. | | [download](#stencil-download) | Downloads the theme files from the active theme on your live store, overwriting local files if desired. | | [push](#stencil-push) | Bundles the theme into `.zip` file; then directly uploads the `.zip` to BigCommerce. | | [release](#stencil-release) | Creates a new release in a theme's GitHub repository. | | [help](#stencil-help) | Displays help and returns all the options available to use for the specified command. | ![Basic Stencil CLI Options and Commands](/_fern-img/3b7b36c5e531a87c55da137fb2e5932cbf8f04ea16014b77afdfb866eafb8f84.webp) ## stencil help Displays help and returns all options available for the specified command. **`Usage: stencil help`** ```shell title="Usage: stencil help" showLineNumbers={false} stencil help COMMAND ``` **`Example: stencil help`** ```shell title="Example: stencil help" showLineNumbers={false} ~ $ stencil help Usage: stencil [OPTIONS] COMMAND Options: -V, --version output the version number -h, --help output usage information ... ``` ## stencil init Creates a `.stencil` file or `secrets.stencil.json` and `config.stencil.json` files (if using Stencil V3.1 release or later) used to configure the live preview when `stencil start` is run. You can specify the configuration information using the optional switches; if you do not specify the configuration information via options, Stencil CLI will prompt you to do so. NOTE: For custom templates, use only the `config.stencil.json` file. The `config.stencil.json` file contains theme-related configuration information like store URL, custom templates, etc. The `secrets.stencil.json` file contains the access token. **`Usage: stencil init`** ```shell title="Usage: stencil init" showLineNumbers={false} stencil init [--url STORE_URL] [--token API_TOKEN] ``` | Option | Alias | Description | | ------------------- | ----- | ------------------------------------------------------------------------------------------ | | `--port HTTP_PORT` | `-p` | The `HTTP` port number to use when serving the live theme preview. | | `--token API_TOKEN` | `-t` | The [BigCommerce API Token](https://support.bigcommerce.com/s/article/Store-API-Accounts). | | `--url STORE_URL` | `-u` | The BigCommerce storefront URL. | ## stencil start Starts the live theme preview using the theme files in the current directory. **`Usage: stencil start`** ```shell title="Usage: stencil start" showLineNumbers={false} stencil start [-V|--version] [-o|--open] [-v|--variation] [-t|--test] [-t|--tunnel] [-vb|--verbose] stencil start [-h|--help] ``` **`Example: stencil start`** ```shell title="Example: stencil start" showLineNumbers={false} stencil start --open # opens live theme preview in default browser ``` | Option | Alias | Description | | ------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `--version` | `-V` | Output the version number | | `--open` | `-o` | Automatically open default browser | | `--variation NAME` | `-v` | Set which theme variation to use while developing | | `--channelId CHANNELID` | `-c` | Set the channel id for the storefront | | `--channelUrl CHANNELURL` | `-cu` | Set the channel URL to bypass custom domain protections. | | `--timeout` | `-t` | Set a timeout for the bundle operation. Default is 20 secs | | `--tunnel` | | Create a tunnel URL that points to your local server, which anyone can use. The required password for external connections is your public IP address. | | `--no-cache` | `-n` | Turn off caching for API resource data (cache refreshes every 5 minutes) | | `--verbose` | `-vb` | Enable verbose logging | | `--help` | `-h` | Output usage information | > **Note** > > #### --theme-editor and --theme-editor-port \[port]: > > BigCommerce deprecated `-theme-editor` and `--theme-editor-port [port]` options as of v1.23.1. Please use [Page Builder](/developer/docs/storefront/stencil/content/page-builder) instead. > **Note** > > #### Authentication errors > > If you receive an `Unauthorized, please use a valid username/token` error, authentication has failed. Make sure the API token you supplied is correct. For more information on creating store API accounts and generating tokens, see [Obtaining Store API Credentials](/developer/docs/storefront/stencil/cli/development-server#creating-stencil-api-credentials). ## stencil bundle Bundles up the theme into a structured `.zip` file, which can be uploaded to BigCommerce. **`Usage: stencil bundle`** ```shell title="Usage: stencil bundle" showLineNumbers={false} stencil bundle [OPTIONS] ``` | Option | Alias | Description | | -------------------- | ----- | --------------------------------------------------------------------------------------------------------- | | `--dest DESTINATION` | `-d` | Where to save the zip file. It defaults to the current directory you are in when bundling (default: `./`) | | `--source-maps` | `-s` | Include source-maps in the bundle. This is useful for debugging. | | `--name FILENAME` | `-n` | What do you want to call the zip file. | | `--marketplace` | `-m` | Runs extra bundle validations for partners who can create marketplace themes. | | `--timeout TIMEOUT` | `-t` | Set a timeout for the bundle operation. (default: "60") | | `--help` | `-h` | Output usage information | ## stencil pull Pulls the configuration from the active theme on your live store and updates your local configuration. This is useful if any theme settings have been changed within Page Builder, as it will prevent you from overwriting them with your next theme upload by first syncing them. **`Usage: stencil pull`** ```shell title="Usage: stencil pull" showLineNumbers={false} stencil pull [OPTIONS] ``` | Option | Alias | Description | | ------------------------- | ----- | --------------------------------------------------------------------------------- | | `--host HOSTNAME` | `-h` | Specify the API host (default: `api.bigcommerce.com`) | | `--filename FILENAME` | `-f` | Specify the filename to use for the merged configuration (default: `config.json`) | | `--saved` | `-s` | Downloads the most recently saved configuration instead of the live one. | | `--channel_id CHANNEL_ID` | `-c` | Specify the channel ID of the storefront, if the store has multiple storefronts. | | `--help` | `-h` | Output usage information | **`Example: stencil pull`** ```shell title="Example: stencil pull" showLineNumbers={false} stencil pull ``` ## stencil push Bundles up the theme into a structured `.zip file`; then directly uploads (pushes) the `.zip` to BigCommerce. **`Usage: stencil push`** ```shell title="Usage: stencil push" showLineNumbers={false} stencil push [] ``` | Option | Alias | Description | | -------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------- | | `--version` | `-V` | Output the version number | | `--host HOSTNAME` | | Specify the API host (default: `api.bigcommerce.com`) | | `--file FILENAME` | `-f` | Specify the filename of the bundle to upload | | `--save FILENAME` | `-s` | Specify the filename of the saved bundle | | `--source-maps` | `-S` | Include source-maps in the bundle. This is useful for debugging. | | `--channel_ids CHANNEL_ID` | `-c` | Specify the channel ID(s) of the storefront, if the store has multiple storefronts | | `--activate VARIATIONNAME` | `-a` | Skip activation prompt; specify variation or leave blank to select first variation | | | `-a -c {{channel_id_1 channel_id_2 ... channel_id_n}}` | Allows you to apply a theme to selected channels (at least one channel id should be provided) | | | `-a -all_channels` or `a -allc` | Allows you to apply a theme to all available channels. | | `--delete` | `-d` | Delete oldest private, non-active theme if upload limit reached | | `--help` | `-h` | Output usage information | **`Example: stencil push`** ```shell title="Example: stencil push" showLineNumbers={false} stencil push -f Cornerstone-2.3.2.zip # uploads specified file, skips bundling if file already exists ``` > **Note** > > #### --filename: > > 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. > When you run `stencil push`, you can apply one theme to multiple storefront or channels. > 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. ## stencil download Download the theme files from your live store, overwriting files in your local directory. **`Usage: stencil download`** ```shell title="Usage: stencil download" showLineNumbers={false} stencil download [OPTIONS] ``` | Option | Alias | Description | | ------------------------- | ----- | ----------------------------------------------------------------------------------- | | `--host HOSTNAME` | `-h` | Specify the API host (default: `api.bigcommerce.com`) | | `--file FILENAME` | `-f` | Specify a single file to download from the theme, e.g. `templates/layout/base.html` | | `--exclude` | `-e` | Specify a directory to exclude from the download. | | `--channel_id CHANNEL_ID` | `-c` | Specify the channel ID of the storefront, if the store has multiple storefronts. | | `--help` | `-h` | Output usage information | **`Example: stencil download`** ```shell title="Example: stencil download" showLineNumbers={false} stencil download -f package.json ``` ## stencil 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. **`Usage: stencil release`** ```shell title="Usage: stencil release" showLineNumbers={false} stencil release [OPTIONS] ``` | Option | Alias | Description | | ----------- | ----- | ------------------------- | | `--version` | `-V` | Output the version number | | `--help` | `-h` | Output usage information | ## Resources ### Related Articles * [Authorizing and Initializing the CLI](/developer/docs/storefront/stencil/cli/install) * [Troubleshooting Your Setup](/developer/docs/storefront/stencil/cli/unexpected-behavior)