DocumentationAPI Reference

Upgrade your theme automatically with ZCLI

Upgrading your theme's templating version automatically with ZCLI

Upgrading a Help Center theme across Templating API versions can be a lot of work. The zcli themes:migrate command automates this for you. It upgrades a theme that uses the Templating API v1 or v2 to v3, and reproduces the built-ins your theme relied on as theme-owned code so the upgraded theme keeps working on its own.

The themes:migrate command is in an early beta stage. It won't produce a perfect result for every theme, but it already handles the largest part of the upgrade and is worth trying today. We're continuing to improve it, and support for upgrading to v4 is coming.

Important: This is a safe process — it never touches your live help center. The command only edits local files, previewing runs entirely on your machine, and importing creates a new theme. Your current theme stays live until you choose to switch to the migrated one.

What it supports

The tool migrates themes on Templating API v1 or v2 up to v3. If your theme is already on v3, there's nothing to migrate yet (v4 support is coming). Running the command on a v3 or v4 theme returns an error.

Prerequisites

  • ZCLI 1.1.4 or newer, authenticated. If you're new to ZCLI, see Using ZCLI. Authenticate with zcli login -i.
  • The theme is in a local folder. If the theme currently lives in your help center, download it first. In Knowledge admin, go to Customize design > your theme > Download theme. See Importing and downloading your theme in Zendesk help.
  • Version control (strongly recommended), on a separate branch. The command rewrites your theme files in place, so working in version control lets you review the changes and revert easily if needed.

Migrating to a new API version and previewing

To try the tool and see the result:

  1. From the theme's root folder, run:

    zcli themes:migrate

    The command upgrades the theme to v3 in place and prints a report, grouped by page, of what the tool changed and how to verify each change.

  2. Preview the migrated theme locally:

    zcli themes:preview

If that's as far as you want to go for now, you can stop here. Trying it out and sending us feedback is valuable on its own.

Adopting the migrated theme when you're ready

When you want to start using the migrated theme:

  1. Review the changes.

With the theme in version control, git diff (or your editor's source-control view) shows exactly what the tool changed. 2. Import it as a new theme.

zcli themes:import

This creates a new theme in Customize design, leaving your current theme untouched and live. 3. Test the new theme. Use the per-page hints from the migration report to guide your testing. 4. Set it live once you're confident everything still works.

Validating the migrated theme

The tool's goal is a backwards-compatible upgrade that requires no further work from you. In practice, because so much changed across Templating API versions, that isn't always achievable — so we strongly encourage testing before you set the migrated theme live. The more customized your theme is, the more testing we recommend. Because importing creates a new theme, you can take as long as you need to test without affecting your live help center.

Reporting issues

If the tool fails to migrate your theme or produces an unexpected result, please let us know so we can improve it. Open an issue in the ZCLI repository or file a ticket with Zendesk support.