{"_id":"591d39877003a30f000ba790","project":"55a6e72e8cc73e0d00096635","category":{"_id":"5605f2bba4574a0d00811365","__v":26,"pages":["5608e4d6c5cff70d007d00d5","5608e4e7c5cff70d007d00d8","5608e4fbc5cff70d007d00da","5608e5096d8c440d000c79f3","5608e5156d8c440d000c79f6","5608e52331beb60d001b6558","5608e8248aedf50d0004cf98","5608e87e8aedf50d0004cf9b","5609bf4f9f85a70d00908530","562822dd5cfea90d00ddc5d7","562831c40653060d00a2f750","563d2732260dde0d00c5eab1","5660d2bee163310d006b19c1","567bb35b93919f0d00c97b1c","567bba643241c20d00b730de","567bbc14b56bac0d0019d933","567bc0473241c20d00b730e5","568b6bd8fe6fcc0d006dc8f7","56a427125fb2530d00421b67","56a42a5194ec0a0d00b3a012","56a42aaa545bc50d000e3ada","56ddff97bea78e20003a778f","56de00ab26744429006648ba","56de12a33168720e00c11b02","56e37f388b32a10e00f79755","56e73362e622c90e00dc55b3"],"project":"55a6e72e8cc73e0d00096635","version":"55a6e72f8cc73e0d00096638","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-26T01:19:55.795Z","from_sync":false,"order":2,"slug":"installation-and-launch","title":"Installation and Launch"},"user":"55a6caa022cfa321008e01d6","__v":0,"parentDoc":null,"version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-05-18T06:04:55.962Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":15,"body":"[block:html]\n{\n  \"html\": \"<A NAME=\\\"Initializing\\\"></a>\"\n}\n[/block]\nTo initialize a Stencil theme for local development, you must reference a BigCommerce storefront. Use one of the following procedures to authorize your theme on the store:\n\n* [Authorizing with OAuth Tokens](#oauth) – Recommended\n* [Authorizing with Legacy (Basic-Auth) Tokens](#legacy) – Workaround\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"OAuth Encouraged; Basic Auth Pending Deprecation\",\n  \"body\": \"As of Stencil CLI version 1.10.0, the `stencil init` command (described below) defaults to OAuth authentication. We strongly encourage you to [generate all new API accounts/tokens as OAuth](/docs/creating-an-api-account#oauth), to ensure these accounts' compatibility with all current and planned BigCommerce features, including our [Themes API](https://developer.bigcommerce.com/api/v3/openapi-v3.html#themes). (However, note that currently, only the store owner can *create* OAuth accounts/tokens.)\\n\\nBigCommerce plans to eventually deprecate [Basic Auth/Legacy API](https://support.bigcommerce.com/articles/Public/Legacy-API-Accounts) accounts/tokens. However, for Stencil themes that you have already initialized/authorized, the `stencil start` command still supports your existing Legacy API accounts/tokens. Also, this page includes workarounds for [using Legacy API accounts/tokens](#legacy), to support stores whose workflow requires that non–store owners be able to create accounts.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Best Practice: Isolate Stores by Subdirectory\",\n  \"body\": \"Even when you share a theme across storefronts, we strongly recommend that you clone a separate subdirectory (each containing its own <span class=\\\"inline-code\\\">.stencil</span> file) for each store. This helps isolate and secure each merchant's data.\\n\\nYou can clone your <span class=\\\"inline-code\\\">.../cornerstone/</span> subdirectory now to create your first isolated copy, and then switch to the resulting new subdirectory to continue. (Prior to March 2017, Stencil's default subdirectory name was <span class=\\\"inline-code\\\">.../stencil/</span>.)\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2 id=\\\"oauth\\\"> Authorizing with OAuth Tokens – Recommended </h2>\\n\\nUse the following steps to authorize your theme using an OAuth API account:\\n\\n<ol>\\n<li>\\n  Have your store API account's <span class=\\\"inline-code\\\">Client ID</span> and <span class=\\\"inline-code\\\">Access Token</span> hashes ready. <br>\\n  (Refer back to the <NOBR><a href=\\\"/docs/copying-a-token-to-initialize-stencil#oauth\\\">Copying a Token to Initialize Stencil</a></nobr> or <a href=\\\"/docs/creating-an-api-account#oauth\\\">Creating an API Account</a> instructions.)<p></p>\\n</li>\\n  \\n<li>Starting from the subdirectory for the appropriate theme (and store), initialize Stencil CLI by running the following command:</li><p></p>\\n\\n<pre>\\nstencil init</pre>\\n\\n<li>You will be prompted to provide the homepage URL of the production store against which you want to develop. This can be your own store, or a client store that you are customizing.<p></p></li>\\n\\n</ol>\"\n}\n[/block]\n<a name=\"https\"></a>\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Use HTTPS (Secure) Protocol for OAuth\",\n  \"body\": \"If you have previously initialized this theme, the prompt will echo the last store URL you entered. If this URL starts with `http:`, update it now to specify the `https:` (HTTP Secure) protocol. Otherwise, while you will be able to launch your theme, some subsequent commands (like [`stencil push`](/docs/bundling-submitting#push)) will fail due to authorization errors.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<ol start=\\\"4\\\">\\n\\n<li>Next, you will be prompted to enter the port where you would like to run your store on your local machine. This can be any port you like, but we recommend using port <span class=\\\"inline-code\\\">3000</span>.\\n<p></p></li>\\n\\n<li>\\n  Next, you will be prompted: <span class=\\\"inline-code\\\">What is your Stencil OAuth Client ID?</span> Enter your store API account's <NOBR><span class=\\\"inline-code\\\">Client ID</span></nobr>.\\n  <p></p>\\n<img src=\\\"https://files.readme.io/4f69119-Token-Challenge-Client-ID.png\\\" alt=\\\"Initializing with OAuth\\\" height=\\\"100%\\\" width=\\\"100%\\\" style=\\\"border:1px solid #D1D7E0\\\"></span>\\n  <p></p>\\n  (If you used this <span class=\\\"inline-code\\\">Client ID</span> when you last ran <span class=\\\"inline-code\\\">stencil init</span>, you'll see it hinted on the command line, and can just confirm it.)\\n<p></p></li>\\n\\n<li>\\nFinally, you will be prompted: <span class=\\\"inline-code\\\">What is your Stencil OAuth Access Token?</span> If you entered these credentials when you last ran <span class=\\\"inline-code\\\">stencil init</span>, you'll see the token hinted in cleartext. If not, paste your <span class=\\\"inline-code\\\">Access Token</span> hash onto the command line. <NOBR>Then press <span class=\\\"inline-code\\\">Enter</span>.</nobr> \\n  <p></p>\\n<img src=\\\"https://files.readme.io/53f0ba3-Token-Challenge-Access-Token.png\\\" alt=\\\"Initializing with OAuth\\\" height=\\\"100%\\\" width=\\\"100%\\\" style=\\\"border:1px solid #D1D7E0\\\"></span>\\n  <p></p>\\n</li>\\n</ol>\\n\\nYour terminal window should now confirm that you have successfully initialized Stencil CLI on your local machine. With Stencil CLI  initialized, you are ready to <a href=\\\"/docs/running-stencil-locally\\\">start Stencil</a> and begin development.\\n  <p></p>\\n\\n<img src=\\\"https://files.readme.io/17a134c-Token-Challenge-Complete-Success.png\\\" alt=\\\"Initializing with OAuth\\\" height=\\\"90%\\\" width=\\\"90%\\\" style=\\\"border:1px solid #D1D7E0\\\"></span>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"You can switch between stores by editing the <span class=\\\"inline-code\\\">.stencil</span> file inside a single theme directory, or by re-running <span class=\\\"inline-code\\\">stencil init</span> in a single theme directory. However, we strongly recommend maintaining separate subdirectories per store, as outlined above.\",\n  \"title\": \"Switching Stores\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2 id=\\\"legacy\\\"> Authorizing with Legacy (Basic-Auth) Tokens – Workaround </h2>\\n\\nIf your workflow does not allow the store owner to create or share an OAuth token, use the following procedure to authorize your theme using a Legacy API account: \\n\\n<ul>\\n <li><a href=\\\"#dot-stencil\\\">Check/Edit the .stencil File</a></li>\\n <li><a href=\\\"#init\\\">Initialize the Theme</a></li>\\n <li><a href=\\\"#convert\\\">How to Convert to OAuth</a></li>\\n</ul>\\n\\n<h3 id=\\\"dot-stencil\\\"> Check/Edit the .stencil File </h2>\\n\\nIf you have installed Stencil CLI version 1.10.0 or higher, you will need to manually edit your <NOBR><span class=\\\"inline-code\\\">&lt;theme-name&gt;/.stencil</span></nobr> credentials file. Here is how to check the version, then make any required edits:\\n\\n<ol>\\n<li> On a command line, enter: </li> <p></p>\\n  \\n<pre>stencil --version</pre>\\n\\n<li> If Stencil CLI responds with a version number below 1.10.0, no file edits are required. Skip directly ahead to <a href=\\\"#init\\\">Initialize the Theme</a>. Otherwise: </li> <p></p>\\n\\n<li> Back up your <span class=\\\"inline-code\\\">&lt;theme-name&gt;/.stencil</span> file.</li><p></p>\\n\\n<li> Open <span class=\\\"inline-code\\\">&lt;theme-name&gt;/.stencil</span> in any text editor. Look for the following two lines, which contain OAuth-specific keys:</li><p></p>\\n\\n<pre>  \\\"clientId\\\": \\\"[...]\\\",\\n  \\\"accessToken\\\": \\\"[...]\\\"</pre>\\n\\n<li>If these OAuth <span class=\\\"inline-code\\\">clientId</span> and <span class=\\\"inline-code\\\">accessToken</span> entries are absent, and you instead see legacy entries reading <span class=\\\"inline-code\\\">username</span> and <span class=\\\"inline-code\\\">token</span>, <NOBR>no editing</nobr> is required. Skip directly ahead to <a href=\\\"#init\\\">Initialize the Theme</a>.</li><p></p>\\n\\n  <li>If you <em>do</em> see OAuth <span class=\\\"inline-code\\\">clientId</span> and <span class=\\\"inline-code\\\">accessToken</span> entries, replace them with the following legacy entries. <NOBR>(You will</nobr> supply values for the <span class=\\\"inline-code\\\">...</span> placeholders just below.) Keep the comma between keys:</li><p></p>\\n\\n<pre>  \\\"username\\\": \\\"...\\\",\\n  \\\"token\\\": \\\"...\\\"</pre>\\n\\n<li>\\nIn the BigCommerce control panel, edit the appropriate store Username's Legacy API account, as outlined in <NOBR><a href=\\\"/docs/copying-a-token-to-initialize-stencil#legacy\\\">Copying a Token to Initialize Stencil</a>.</nobr><p></p>\\n</li>\\n\\n<li>\\nCopy and paste the control panel's <span class=\\\"inline-code\\\">Username</span> and <span class=\\\"inline-code\\\">API Token</span> values into your <span class=\\\"inline-code\\\">.stencil</span> file's corresponding fields, replacing the <span class=\\\"inline-code\\\">...</span> placeholders. (Keep the quotes surrounding each value, and the commas between keys.)</nobr><p></p>\\n</li>\\n\\n<li>\\nResave your <span class=\\\"inline-code\\\">.stencil</span> file. Keep the text editor and control panel open for the remaining steps below, in case you need to copy/paste values again.<p></p>\\n</li>\\n</ol>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"A minimal, but complete, `.stencil` file includes two additional entries for `normalStoreUrl` and `port`:\\n\\n```\\n  \\\"normalStoreUrl\\\": \\\"...\\\",\\n  \\\"port\\\": 3000,\\n  \\\"username\\\": \\\"...\\\",\\n  \\\"token\\\": \\\"...\\\"\\n```\\n\\nYou have the option of now pasting in your store URL as the `normalStoreUrl` value, and resaving the `.stencil` file. You can then try skipping the next [Initialize the Theme](#init) section (which just guides you through entering the same value via the command line), and proceeding directly to [`stencil start`](/docs/running-stencil-locally).\",\n  \"title\": \"(Optional:) Bypassing Command-Line Initialization\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h3 id=\\\"init\\\"> Initialize the Theme </h2>\\n\\n<ol>  \\n<li>\\nFor Stencil CLI versions below 1.10.0, place the appropriate store Username's token on your clipboard. <NOBR>(See <a href=\\\"/docs/copying-a-token-to-initialize-stencil#legacy\\\">Copying a Token to Initialize Stencil</a>.</nobr>)<p></p>\\n</li>\\n\\n<li>Starting from the subdirectory for the appropriate theme (and store), initialize Stencil CLI by running the following command:</li><p></p>\\n\\n<pre>\\nstencil init</pre>\\n\\n<li>You will be prompted to provide the homepage URL of the production storefront against which you want to develop locally. This can be your own store, or a client store that you are customizing.<p></p></li>\\n\\n\\t<li>Next, you will be prompted to enter the port where you would like to run your store on your local machine. This can be any port you like, but we recommend using port 3000.\\n<p></p></li>\\n\\n  <li>\\nNext, you will be prompted (depending on your Stencil CLI version): \\\"What is your Stencil OAuth Client ID?\\\" or \\\"What is your Stencil Username?\\\"\\n  <p></p>\\n<img src=\\\"https://files.readme.io/4f69119-Token-Challenge-Client-ID.png\\\" alt=\\\"Initializing with Basic Auth\\\" height=\\\"100%\\\" width=\\\"100%\\\" style=\\\"border:1px solid #D1D7E0\\\"></span>\\n  <p></p>\\n</li>\\n\\n\\t<ul> <!-- inner list -->\\n\\t\\t<li>If you have <a href=\\\"#dot-stencil\\\">manually edited your <span class=\\\"inline-code\\\">.stencil</span> file</a> as described above, leave the command line blank and just press <span class=\\\"inline-code\\\">Enter</span>. (Stencil CLI will use the Username that you have manually inserted into your <span class=\\\"inline-code\\\">.stencil</span> file</a>.) <p></p>\\n    </li>  \\n  \\n\\t\\t<li>If you entered a Basic-Auth Username when you previously ran <span class=\\\"inline-code\\\">stencil init</span>, some versions of <NOBR>Stencil CLI</nobr> will hint this Username on the command line. Just press <span class=\\\"inline-code\\\">Enter</span> to confirm it.<p></p>\\n    </li>  \\n  \\n\\t\\t<li>Otherwise, enter the Basic-Auth Username that corresponds to the token you've copied to your clipboard. <p></p>\\n    </li>\\n\\t</ul> <!-- inner list -->\\n\\n<li> <!-- outer list -->\\nFinally, you will be prompted (depending on your Stencil CLI version): \\\"What is your Stencil OAuth Access Token?\\\" or \\\"What is your Stencil Token?\\\" \\n  <p></p>\\n<img src=\\\"https://files.readme.io/53f0ba3-Token-Challenge-Access-Token.png\\\" alt=\\\"Initializing with Basic Auth\\\" height=\\\"100%\\\" width=\\\"100%\\\" style=\\\"border:1px solid #D1D7E0\\\"></span>\\n  <p></p>\\n</li>\\n\\n\\t<ul> <!-- inner list -->\\n\\t\\t<li>If you have <a href=\\\"#dot-stencil\\\">manually edited your <span class=\\\"inline-code\\\">.stencil</span> file</a>, leave the command line blank and just press <span class=\\\"inline-code\\\">Enter</span>. (Stencil CLI will use the token value that you have manually inserted into your <span class=\\\"inline-code\\\">.stencil</span> file</a>.) <p></p>\\n    </li>  \\n  \\n\\t\\t<li>If you entered a Basic-Auth token when you previously ran <span class=\\\"inline-code\\\">stencil init</span>, some versions of <NOBR>Stencil CLI</nobr> will hint the token's value in cleartext. Just press <span class=\\\"inline-code\\\">Enter</span> to confirm it.<p></p>\\n    </li>  \\n  \\n\\t\\t<li>Otherwise, enter the Basic-Auth token value that you've <a href=\\\"/docs/copying-a-token-to-initialize-stencil#legacy\\\">copied to your clipboard</a>. <p></p>\\n    </li>\\n\\t</ul> <!-- inner list -->\\n\\nYour terminal window should now confirm that you have successfully initialized Stencil CLI on your local machine:\\n  <p></p>\\n<img src=\\\"https://files.readme.io/17a134c-Token-Challenge-Complete-Success.png\\\" alt=\\\"Initializing with Basic Auth\\\" height=\\\"90%\\\" width=\\\"90%\\\" style=\\\"border:1px solid #D1D7E0\\\">\\n  <p></p>\\nWith Stencil CLI  initialized, you are ready to <a href=\\\"/docs/running-stencil-locally\\\">start Stencil</a> and begin development.\\n </ul> <!-- outer list -->\\n</ol> <!-- outer list -->\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Switching Stores\",\n  \"body\": \"You can switch between stores by editing the <span class=\\\"inline-code\\\">.stencil</span> file inside a single theme directory, or by re-running <span class=\\\"inline-code\\\">stencil init</span> in a single theme directory. However, we strongly recommend maintaining separate subdirectories per store, as outlined above.\"\n}\n[/block]\n### <a name=\"convert\"></a> How to Convert to OAuth\n\nIf you have previously initialized a Stencil theme using Basic Auth, and want to re-initialize it using the OAuth credentials that we now recommend: Just re-run `stencil init`, following the OAuth instructions above at [Authorizing with OAuth Tokens – Recommended](#oauth).\n\nBe sure to [re-enter your store's URL](#https) as `https:` (as advised in those instructions).\n\nWhen prompted for the `Stencil OAuth Client ID` and `Stencil OAuth Access Token`, enter your new OAuth credentials. These will overwrite any credentials that you previously used to initialize the theme.","excerpt":"","slug":"initializing-stencil","type":"basic","title":"Authorizing and Initializing Stencil"}

Authorizing and Initializing Stencil


[block:html] { "html": "<A NAME=\"Initializing\"></a>" } [/block] To initialize a Stencil theme for local development, you must reference a BigCommerce storefront. Use one of the following procedures to authorize your theme on the store: * [Authorizing with OAuth Tokens](#oauth) – Recommended * [Authorizing with Legacy (Basic-Auth) Tokens](#legacy) – Workaround [block:callout] { "type": "warning", "title": "OAuth Encouraged; Basic Auth Pending Deprecation", "body": "As of Stencil CLI version 1.10.0, the `stencil init` command (described below) defaults to OAuth authentication. We strongly encourage you to [generate all new API accounts/tokens as OAuth](/docs/creating-an-api-account#oauth), to ensure these accounts' compatibility with all current and planned BigCommerce features, including our [Themes API](https://developer.bigcommerce.com/api/v3/openapi-v3.html#themes). (However, note that currently, only the store owner can *create* OAuth accounts/tokens.)\n\nBigCommerce plans to eventually deprecate [Basic Auth/Legacy API](https://support.bigcommerce.com/articles/Public/Legacy-API-Accounts) accounts/tokens. However, for Stencil themes that you have already initialized/authorized, the `stencil start` command still supports your existing Legacy API accounts/tokens. Also, this page includes workarounds for [using Legacy API accounts/tokens](#legacy), to support stores whose workflow requires that non–store owners be able to create accounts." } [/block] [block:callout] { "type": "danger", "title": "Best Practice: Isolate Stores by Subdirectory", "body": "Even when you share a theme across storefronts, we strongly recommend that you clone a separate subdirectory (each containing its own <span class=\"inline-code\">.stencil</span> file) for each store. This helps isolate and secure each merchant's data.\n\nYou can clone your <span class=\"inline-code\">.../cornerstone/</span> subdirectory now to create your first isolated copy, and then switch to the resulting new subdirectory to continue. (Prior to March 2017, Stencil's default subdirectory name was <span class=\"inline-code\">.../stencil/</span>.)" } [/block] [block:html] { "html": "<h2 id=\"oauth\"> Authorizing with OAuth Tokens – Recommended </h2>\n\nUse the following steps to authorize your theme using an OAuth API account:\n\n<ol>\n<li>\n Have your store API account's <span class=\"inline-code\">Client ID</span> and <span class=\"inline-code\">Access Token</span> hashes ready. <br>\n (Refer back to the <NOBR><a href=\"/docs/copying-a-token-to-initialize-stencil#oauth\">Copying a Token to Initialize Stencil</a></nobr> or <a href=\"/docs/creating-an-api-account#oauth\">Creating an API Account</a> instructions.)<p></p>\n</li>\n \n<li>Starting from the subdirectory for the appropriate theme (and store), initialize Stencil CLI by running the following command:</li><p></p>\n\n<pre>\nstencil init</pre>\n\n<li>You will be prompted to provide the homepage URL of the production store against which you want to develop. This can be your own store, or a client store that you are customizing.<p></p></li>\n\n</ol>" } [/block] <a name="https"></a> [block:callout] { "type": "warning", "title": "Use HTTPS (Secure) Protocol for OAuth", "body": "If you have previously initialized this theme, the prompt will echo the last store URL you entered. If this URL starts with `http:`, update it now to specify the `https:` (HTTP Secure) protocol. Otherwise, while you will be able to launch your theme, some subsequent commands (like [`stencil push`](/docs/bundling-submitting#push)) will fail due to authorization errors." } [/block] [block:html] { "html": "<ol start=\"4\">\n\n<li>Next, you will be prompted to enter the port where you would like to run your store on your local machine. This can be any port you like, but we recommend using port <span class=\"inline-code\">3000</span>.\n<p></p></li>\n\n<li>\n Next, you will be prompted: <span class=\"inline-code\">What is your Stencil OAuth Client ID?</span> Enter your store API account's <NOBR><span class=\"inline-code\">Client ID</span></nobr>.\n <p></p>\n<img src=\"https://files.readme.io/4f69119-Token-Challenge-Client-ID.png\" alt=\"Initializing with OAuth\" height=\"100%\" width=\"100%\" style=\"border:1px solid #D1D7E0\"></span>\n <p></p>\n (If you used this <span class=\"inline-code\">Client ID</span> when you last ran <span class=\"inline-code\">stencil init</span>, you'll see it hinted on the command line, and can just confirm it.)\n<p></p></li>\n\n<li>\nFinally, you will be prompted: <span class=\"inline-code\">What is your Stencil OAuth Access Token?</span> If you entered these credentials when you last ran <span class=\"inline-code\">stencil init</span>, you'll see the token hinted in cleartext. If not, paste your <span class=\"inline-code\">Access Token</span> hash onto the command line. <NOBR>Then press <span class=\"inline-code\">Enter</span>.</nobr> \n <p></p>\n<img src=\"https://files.readme.io/53f0ba3-Token-Challenge-Access-Token.png\" alt=\"Initializing with OAuth\" height=\"100%\" width=\"100%\" style=\"border:1px solid #D1D7E0\"></span>\n <p></p>\n</li>\n</ol>\n\nYour terminal window should now confirm that you have successfully initialized Stencil CLI on your local machine. With Stencil CLI initialized, you are ready to <a href=\"/docs/running-stencil-locally\">start Stencil</a> and begin development.\n <p></p>\n\n<img src=\"https://files.readme.io/17a134c-Token-Challenge-Complete-Success.png\" alt=\"Initializing with OAuth\" height=\"90%\" width=\"90%\" style=\"border:1px solid #D1D7E0\"></span>" } [/block] [block:callout] { "type": "info", "body": "You can switch between stores by editing the <span class=\"inline-code\">.stencil</span> file inside a single theme directory, or by re-running <span class=\"inline-code\">stencil init</span> in a single theme directory. However, we strongly recommend maintaining separate subdirectories per store, as outlined above.", "title": "Switching Stores" } [/block] [block:html] { "html": "<h2 id=\"legacy\"> Authorizing with Legacy (Basic-Auth) Tokens – Workaround </h2>\n\nIf your workflow does not allow the store owner to create or share an OAuth token, use the following procedure to authorize your theme using a Legacy API account: \n\n<ul>\n <li><a href=\"#dot-stencil\">Check/Edit the .stencil File</a></li>\n <li><a href=\"#init\">Initialize the Theme</a></li>\n <li><a href=\"#convert\">How to Convert to OAuth</a></li>\n</ul>\n\n<h3 id=\"dot-stencil\"> Check/Edit the .stencil File </h2>\n\nIf you have installed Stencil CLI version 1.10.0 or higher, you will need to manually edit your <NOBR><span class=\"inline-code\">&lt;theme-name&gt;/.stencil</span></nobr> credentials file. Here is how to check the version, then make any required edits:\n\n<ol>\n<li> On a command line, enter: </li> <p></p>\n \n<pre>stencil --version</pre>\n\n<li> If Stencil CLI responds with a version number below 1.10.0, no file edits are required. Skip directly ahead to <a href=\"#init\">Initialize the Theme</a>. Otherwise: </li> <p></p>\n\n<li> Back up your <span class=\"inline-code\">&lt;theme-name&gt;/.stencil</span> file.</li><p></p>\n\n<li> Open <span class=\"inline-code\">&lt;theme-name&gt;/.stencil</span> in any text editor. Look for the following two lines, which contain OAuth-specific keys:</li><p></p>\n\n<pre> \"clientId\": \"[...]\",\n \"accessToken\": \"[...]\"</pre>\n\n<li>If these OAuth <span class=\"inline-code\">clientId</span> and <span class=\"inline-code\">accessToken</span> entries are absent, and you instead see legacy entries reading <span class=\"inline-code\">username</span> and <span class=\"inline-code\">token</span>, <NOBR>no editing</nobr> is required. Skip directly ahead to <a href=\"#init\">Initialize the Theme</a>.</li><p></p>\n\n <li>If you <em>do</em> see OAuth <span class=\"inline-code\">clientId</span> and <span class=\"inline-code\">accessToken</span> entries, replace them with the following legacy entries. <NOBR>(You will</nobr> supply values for the <span class=\"inline-code\">...</span> placeholders just below.) Keep the comma between keys:</li><p></p>\n\n<pre> \"username\": \"...\",\n \"token\": \"...\"</pre>\n\n<li>\nIn the BigCommerce control panel, edit the appropriate store Username's Legacy API account, as outlined in <NOBR><a href=\"/docs/copying-a-token-to-initialize-stencil#legacy\">Copying a Token to Initialize Stencil</a>.</nobr><p></p>\n</li>\n\n<li>\nCopy and paste the control panel's <span class=\"inline-code\">Username</span> and <span class=\"inline-code\">API Token</span> values into your <span class=\"inline-code\">.stencil</span> file's corresponding fields, replacing the <span class=\"inline-code\">...</span> placeholders. (Keep the quotes surrounding each value, and the commas between keys.)</nobr><p></p>\n</li>\n\n<li>\nResave your <span class=\"inline-code\">.stencil</span> file. Keep the text editor and control panel open for the remaining steps below, in case you need to copy/paste values again.<p></p>\n</li>\n</ol>" } [/block] [block:callout] { "type": "info", "body": "A minimal, but complete, `.stencil` file includes two additional entries for `normalStoreUrl` and `port`:\n\n```\n \"normalStoreUrl\": \"...\",\n \"port\": 3000,\n \"username\": \"...\",\n \"token\": \"...\"\n```\n\nYou have the option of now pasting in your store URL as the `normalStoreUrl` value, and resaving the `.stencil` file. You can then try skipping the next [Initialize the Theme](#init) section (which just guides you through entering the same value via the command line), and proceeding directly to [`stencil start`](/docs/running-stencil-locally).", "title": "(Optional:) Bypassing Command-Line Initialization" } [/block] [block:html] { "html": "<h3 id=\"init\"> Initialize the Theme </h2>\n\n<ol> \n<li>\nFor Stencil CLI versions below 1.10.0, place the appropriate store Username's token on your clipboard. <NOBR>(See <a href=\"/docs/copying-a-token-to-initialize-stencil#legacy\">Copying a Token to Initialize Stencil</a>.</nobr>)<p></p>\n</li>\n\n<li>Starting from the subdirectory for the appropriate theme (and store), initialize Stencil CLI by running the following command:</li><p></p>\n\n<pre>\nstencil init</pre>\n\n<li>You will be prompted to provide the homepage URL of the production storefront against which you want to develop locally. This can be your own store, or a client store that you are customizing.<p></p></li>\n\n\t<li>Next, you will be prompted to enter the port where you would like to run your store on your local machine. This can be any port you like, but we recommend using port 3000.\n<p></p></li>\n\n <li>\nNext, you will be prompted (depending on your Stencil CLI version): \"What is your Stencil OAuth Client ID?\" or \"What is your Stencil Username?\"\n <p></p>\n<img src=\"https://files.readme.io/4f69119-Token-Challenge-Client-ID.png\" alt=\"Initializing with Basic Auth\" height=\"100%\" width=\"100%\" style=\"border:1px solid #D1D7E0\"></span>\n <p></p>\n</li>\n\n\t<ul> <!-- inner list -->\n\t\t<li>If you have <a href=\"#dot-stencil\">manually edited your <span class=\"inline-code\">.stencil</span> file</a> as described above, leave the command line blank and just press <span class=\"inline-code\">Enter</span>. (Stencil CLI will use the Username that you have manually inserted into your <span class=\"inline-code\">.stencil</span> file</a>.) <p></p>\n </li> \n \n\t\t<li>If you entered a Basic-Auth Username when you previously ran <span class=\"inline-code\">stencil init</span>, some versions of <NOBR>Stencil CLI</nobr> will hint this Username on the command line. Just press <span class=\"inline-code\">Enter</span> to confirm it.<p></p>\n </li> \n \n\t\t<li>Otherwise, enter the Basic-Auth Username that corresponds to the token you've copied to your clipboard. <p></p>\n </li>\n\t</ul> <!-- inner list -->\n\n<li> <!-- outer list -->\nFinally, you will be prompted (depending on your Stencil CLI version): \"What is your Stencil OAuth Access Token?\" or \"What is your Stencil Token?\" \n <p></p>\n<img src=\"https://files.readme.io/53f0ba3-Token-Challenge-Access-Token.png\" alt=\"Initializing with Basic Auth\" height=\"100%\" width=\"100%\" style=\"border:1px solid #D1D7E0\"></span>\n <p></p>\n</li>\n\n\t<ul> <!-- inner list -->\n\t\t<li>If you have <a href=\"#dot-stencil\">manually edited your <span class=\"inline-code\">.stencil</span> file</a>, leave the command line blank and just press <span class=\"inline-code\">Enter</span>. (Stencil CLI will use the token value that you have manually inserted into your <span class=\"inline-code\">.stencil</span> file</a>.) <p></p>\n </li> \n \n\t\t<li>If you entered a Basic-Auth token when you previously ran <span class=\"inline-code\">stencil init</span>, some versions of <NOBR>Stencil CLI</nobr> will hint the token's value in cleartext. Just press <span class=\"inline-code\">Enter</span> to confirm it.<p></p>\n </li> \n \n\t\t<li>Otherwise, enter the Basic-Auth token value that you've <a href=\"/docs/copying-a-token-to-initialize-stencil#legacy\">copied to your clipboard</a>. <p></p>\n </li>\n\t</ul> <!-- inner list -->\n\nYour terminal window should now confirm that you have successfully initialized Stencil CLI on your local machine:\n <p></p>\n<img src=\"https://files.readme.io/17a134c-Token-Challenge-Complete-Success.png\" alt=\"Initializing with Basic Auth\" height=\"90%\" width=\"90%\" style=\"border:1px solid #D1D7E0\">\n <p></p>\nWith Stencil CLI initialized, you are ready to <a href=\"/docs/running-stencil-locally\">start Stencil</a> and begin development.\n </ul> <!-- outer list -->\n</ol> <!-- outer list -->" } [/block] [block:callout] { "type": "info", "title": "Switching Stores", "body": "You can switch between stores by editing the <span class=\"inline-code\">.stencil</span> file inside a single theme directory, or by re-running <span class=\"inline-code\">stencil init</span> in a single theme directory. However, we strongly recommend maintaining separate subdirectories per store, as outlined above." } [/block] ### <a name="convert"></a> How to Convert to OAuth If you have previously initialized a Stencil theme using Basic Auth, and want to re-initialize it using the OAuth credentials that we now recommend: Just re-run `stencil init`, following the OAuth instructions above at [Authorizing with OAuth Tokens – Recommended](#oauth). Be sure to [re-enter your store's URL](#https) as `https:` (as advised in those instructions). When prompted for the `Stencil OAuth Client ID` and `Stencil OAuth Access Token`, enter your new OAuth credentials. These will overwrite any credentials that you previously used to initialize the theme.