Previewing theme changes locally

<div class="article-banners">
<div id="docs-wmp-link"><a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" rel="noopener" target="_blank">What's my plan?</a></div>
<div class="article-banner" id="suite_gpee">
<table>
<tbody>
<tr>
<td>
<strong>All Suites</strong>
</td>
<td>Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr>
</tbody>
</table>
</div>
<div class="article-banner" id="support_with_guide_all">
<table>
<tbody>
<tr>
<td>
<strong>Support with</strong>
</td>
<td>Knowledge Professional or Enterprise</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="body">
<p class="p">You can work on a theme in your preferred code editor locally and preview your changes live
in a web browser. You don't have to upload the files to Guide every time you want to preview
your changes. A background process running on your computer uploads your changes for you every
time you save a file locally.</p>
<p class="p">Example:</p>
<p class="p"><img class="image img-screenshot" id="topic_utj_p2h_2db__image_dlf_wf3_2db" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/theme_local_preview.png" width="600"></p>
<p class="p">Topics covered in this article:</p>
<ul class="ul" id="topic_utj_p2h_2db__ul_jkk_twn_2db">
<li class="li"><a class="xref" href="#topic_kmy_mfh_2db">Setting up local theme previewing</a></li>
<li class="li"><a class="xref" href="#topic_h54_tp3_2db">Starting local theme previewing</a></li>
<li class="li"><a class="xref" href="#topic_w2z_5wn_2db">Previewing changes</a></li>
</ul>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_kmy_mfh_2db">
<h2 class="title topictitle2" id="ariaid-title2">Setting up local theme previewing</h2>
<div class="body">
<p class="p">Setting up local theme previewing consists of downloading the theme files, enabling API
access in your account, and installing the Zendesk Command Line Interface (ZCLI) on your
computer. The ZCLI enables local theme previewing.</p>
<p class="p"><strong class="ph b">To set up local theme previewing</strong></p>
<ol class="ol" id="topic_kmy_mfh_2db__ul_hhq_5k3_2db">
<li class="li">Download the theme files from Guide and unzip them in a working folder. <p class="p">See <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408828976538#topic_udw_zdc_hbb" target="_blank">Downloading a help center theme</a>.</p>
</li>
<li class="li">If not already done, enable API access in your Zendesk account.<p class="p"><span class="ph">In <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank">Admin Center</a>, click <img class="image" id="topic_kmy_mfh_2db__d7e1783" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_apps_integrations_icon.png">
<strong class="ph b">Apps and integrations</strong> in the sidebar, then select <strong class="ph b">APIs &gt; Zendesk API</strong>.</span></p>
</li>
<li class="li">Install the ZCLI. See <a class="xref" href="https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/#installing-and-updating-zcli" target="_blank">Installing and updating ZCLI</a> in the Zendesk
developer documentation.</li>
</ol>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_h54_tp3_2db">
<h2 class="title topictitle2" id="ariaid-title3">Starting local theme previewing</h2>
<div class="body">
<p class="p">You must start local theme previewing before you start working on theme files on your
computer.</p>
<p class="p"><strong class="ph b">To start local theme previewing</strong></p>
<ol class="ol" id="topic_h54_tp3_2db__ol_ht1_1q3_2db">
<li class="li">In your computer's command line terminal, navigate to the folder containing the
downloaded and unzipped theme files.
Example:<pre class="pre codeblock"><code>cd guide_themes/newlook_theme</code></pre>
</li>
<li class="li">Sign into the Zendesk account where you downloaded the theme.<div class="p">
<pre class="pre codeblock"><code>zcli login -i</code></pre>
</div>
<p class="p">At the prompts, enter your subdomain, email, and API token. You don't need to
append "/token" to your email address. ZCLI appends this suffix for you.</p>
<p class="p">Use your
account's standard Zendesk subdomain to sign in. Don't use any host mapped
subdomain.</p>
</li>
<li class="li">Start the background process for local previewing:<div class="p">
<pre class="pre codeblock"><code>zcli themes:preview </code></pre>
</div>
<p class="p">This ZCLI command starts local previewing and uploads the local theme in Preview
mode to your help center. Changes you make to the files locally will be reflected in the
theme in Preview mode.<img class="image" id="topic_h54_tp3_2db__image_g53_zq1_vxb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/theme_local_preview_start.png" width="450"></p>
</li>
<li class="li">Copy the "Ready" URL and paste it in a web browser such as Chrome or Firefox. <p class="p">The
browser must allow mixed HTTP and HTTPS content. Safari doesn't support mixed content
and won't allow you to preview themes locally.</p>
<p class="p">The "Ready" URL looks like
<strong class="ph b">https://yoursubdomain.zendesk.com/hc/admin/local_preview/start</strong>.</p>
</li>
</ol>
<p class="p">For more information about the ZCLI preview command, see <a class="xref" href="https://github.com/zendesk/zcli/blob/master/docs/themes.md" target="_blank">zcli themes</a> on GitHub.</p>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested1" id="topic_w2z_5wn_2db">
<h2 class="title topictitle2" id="ariaid-title4">Previewing changes</h2>
<div class="body">
<p class="p">After ZCLI uploads your theme in Preview mode to your help center, you can work on your
theme files locally in your favorite code editor and preview the changes in your browser.
Work iteratively to develop and test your theme. For example, make some changes to a file,
save the file, then check your changes in the browser. Fix any issues with the changes
before making additional changes.</p>
<p class="p"><strong class="ph b">To preview changes</strong></p>
<ol class="ol" id="topic_w2z_5wn_2db__ol_mrj_txn_2db">
<li class="li">Save the edited file or files in your code editor.</li>
<li class="li">Check the results in the theme in Preview mode in your browser.</li>
</ol>
<p class="p">The theme reloads automatically in the browser when you save a file locally. You don't need
to refresh the page. </p>
<p class="p">There's a ZCLI option to disable live reloads. See <a class="xref" href="https://github.com/zendesk/zcli/blob/master/docs/themes.md" target="_blank">zcli themes</a> on GitHub.</p>
<p class="p">When you're done for the day, you can stop Preview mode using one of the following
methods:</p>
<ul class="ul" id="topic_w2z_5wn_2db__ul_qpl_zwn_2db">
<li class="li">In the terminal session running ZCLI, press <strong class="ph b">Ctrl</strong>+<strong class="ph b">C</strong>.</li>
<li class="li">Open <strong class="ph b">https://yoursubdomain.zendesk.com/hc/admin/local_preview/stop</strong> in your
browser, with your actual subdomain in the URL.</li>
<li class="li">At the top of the browser's theme preview page, click the <strong class="ph b">Close preview</strong>
link.</li>
</ul>
</div>
</div>
<script id="docs-schema-markup" type="application/ld+json">{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408822095642",
"url": "https://support.zendesk.com/hc/en-us/articles/4408822095642-Previewing-theme-changes-locally",
"headline": "Previewing theme changes locally",
"description": "You can set up and start local theme previewing by downloading theme files, enabling API access, installing a command line interface, and using it to upload and preview changes live in a browser without manual uploads.",
"articleSection": "Using themes and customizing your help center",
"datePublished": "2021-10-16T03:33:22+00:00",
"dateModified": "2026-01-21T19:42:50+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408822095642"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"@id": "https://support.zendesk.com/hc/"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk",
"@id": "https://www.zendesk.com",
"softwareAddOn": {
"@type": "SoftwareApplication",
"name": "Knowledge",
"@id": "https://support.zendesk.com/hc/en-us/sections/4405298860954"
}
}
}</script>