Add a theme using SXA CLI

Current version: 10.3

SXA CLI is a useful command line tool to automatize tasks for an SXA project. This topic describes how to add a theme using SXA CLI. This can be convenient if you want to have more control over your assets and use a version control system, such as Git.

To be able to add a theme using SXA CLI:

You must have sufficient permissions. You must either have the sitecore\Powershell Extensions Remoting role assigned or add the user to the /configuration/sitecore/powershell/services/restfulv2/authorization config node.

RequestResponse

<configuration>
 <sitecore>
  <powershell>
    <services>
      <restfulv2>
        <authorization>
         <add Permission="Allow" IdentityType="User" Identity="sitecore\username" />
          </authorization>
        </restfulv2>
    </powershell>
  </sitecore>
</configuration>

Install Node Package Manager (NPM) globally: Use npm and the install command to install SXA CLI as a global package: npm i -g @sitecore/sxa-cli. This uses the newest CLI available.

To add a theme using SXA CLI:

Download the the Sitecore theme boilerplate.
Go to Website\App_Config\Include\z.Feature.Overrides and enable the z.SPE.Sync.Enabler.Gulp.config.disabled file.
Switch to the downloaded theme boilerplate folder.
Run sxa init.
Add a URL for uploading. You have three options: You can use serverUrlStrategy to dedicate a local or global strategy, or you can specify a URL via a CLI option.
- ServerUrlStrategy: 'local': Sends files to the path for your Sitecore instance registered under serverOptions.server in the config file for Gulp tasks (ThemeRoot/gulp/config.js).
- ServerUrlStrategy: 'global': Takes the value registered by the CLI. If SXA cannot find this path, it falls back as if it was set up to local.
- -u, --url - <Instance URL>: upload files to the instance URL, for example -url https://sxa-instance.test. If you specify a URL this way, the tasks ignore the serverUrlStrategy property and take their value from the CLI option. For more information about CLI options, see The SXA CLI watch, (re)build, and upload tasks.
If you use Creative Exchange, skip this step.

Open ThemeRoot/gulp/serverConfig.json and enter:
- serverOptions.projectPath - the path to the project where the theme is placed.
- serverOptions.themePath - the path to the basic theme folder from the project root.
Open the Theme root folder with the command line.
Run npm i.
Your new theme is now available. You must assign your new theme to your site:

Go to Sitecore/Content/<tenant>/<site>/Settings, and in the Site Configuration settings, in the Compatible themes field add your new theme to the Selected field. Now you can select the theme as your site's current theme.

The following table describes the most important commands for using SXA CLI in your theme setup:

Command	Alias	Description
`sxa init`	`sxa i`	Downloads all necessary files for compatibility with the Creative Exchange Live Mode. This process downloads the missing files and does not replace existing files.
`sxa new <ThemeName> --url <url>`	`sxa n`	Runs the create theme pipeline and stores the theme both locally and in Sitecore. Downloads all assets. Use this command to create a new theme for your site. You can add to the instance where the theme should be created. If you want to create the theme in the currently registered Sitecore instance, you don't have to specify the URL.
`sxa config`	`sxa c`	Sets up the theme variable by answering a list of questions. Use this command to change the theme setup.
`sxa register <url>`	`sxa reg`	Globally registers an instance of Sitecore URL.
`sxa get-url`	`sxa g`	Checks the currently registered URL.
`sxa build [taskName]`	`sxa b`	Builds the theme assets based on the current theme configuration. For available tasks, go to The SXA watch, build, and upload tasks.
`sxa upload [taskName]`	`sxa u`	Uploads the theme assets based on the theme configuration. For available tasks, go to The SXA watch, build, and upload tasks
`sxa watch [taskName]`	`sxa w`	Watches theme asset changes and uploads the modified files automatically. For available tasks, go to The SXA watch, build, and upload tasks Can be configured with `sxa config` command.
`sxa rebuild [taskName]`	`sxa r`	Rebuilds and uploads theme assets. For available tasks, go to The SXA watch, build, and upload tasks

Use SXA CLI with a custom user

If you do not want to use the default sitecore\admin user to upload themes through SXA CLI, you can create a separate user for this purpose.

To create a custom user that can use the SXA CLI:

Open the User Editor, and create a new user.
In the User Editor, assign the sitecore\PowerShell Extensions Remoting role to the user.

Note

In Azure environments, the sitecore\PowerShell Extensions Remoting role does not exist by default. If the role is missing, you must create it in the Role Manager.
Make sure that the user has the following permissions for /sitecore/media library/Themes: Read, Write, Create, Rename, and Delete.
Make sure that the z.SPE.Sync.Enabler.Gulf.config file is enabled. It is located here: \App_Config\Include\z.Feature.Overrides\.

Do you have some feedback for us?

If you have suggestions for improving this article,