Sitecore XM Cloud CLI Cheatsheet updated

I created couple of cheat sheets for XM Cloud CLI earlier this year and it has been viewed more than 5000 times and it has been downloaded more than 1000 times. To keep the cheat sheet up to date, I have updated the cheat sheet and published it. 

To access XM Cloud Cheat Sheet, refer these two links below.

Sitecore XM Cloud CLI Commands List Cheat Sheet by nehem87

Sitecore XM Cloud CLI Cheat Sheet by nehem87

Sitecore XM Cloud CLI New Feature - Organization command

Sitecore updated the CLI with additional cloud command. 'organization'. This fits in along with other commands like login, logout, project, environment and deployment. 

Organization command has three sub commands which helps you to retrieve the organization information, health of the particular organization at that time and retrieve license file. 

In order to quickly update cloud plugin, you can just remove and add it by executing the following in terminal. 

cloud organization info

This sub command helps you to retrieve the currently logged in Organization details. 

cloud organization health

This sub command helps you to display the status of the organization. You can view the health in Sitecore Deploy Portal --> System Health.

cloud organization license

This sub command helps you to download the organization's license. This can be used for your local development. 

Creating an XM Cloud Project from an Existing Sitecore Solution in Bitbucket

In this blog post, I will set up an XM Cloud environment with an existing Sitecore solution.

If you are migrating an existing Sitecore solution to XM Cloud, you must migrate the source to an XM Cloud-compatible solution. To start, you can clone the XM Cloud SXA-based starter template repository. This template solution can be used as a base to migrate all of your existing projects to it. In this blog post, I will use Bitbucket as my repository, add the existing solution, and deploy it to XM Cloud. Please note that XM Cloud does not support MVC solutions. You must migrate or rewrite your MVC solution to a headless SXA solution. 

Clone Template Solution

In Bitbucket, I used the repository import feature to clone and import the template solution from the GitHub template repository. Alternatively, you can simply clone the repository to your local environment or to another Git repository.

Update template solution with the existing solution

From an existing solution perspective, I have only the Scheduled Publish module, which I have added to the template solution and checked in. In your case, you may have many projects, and you will need to migrate them to the XM Cloud-compatible template solution.

Based on Sitecore's recent blog, Sitecore recommends partners adopt industry-standard practices that align with the specific implementation technologies being used. Previously, the Helix architectural guidelines were used for MVC and Sitecore headless projects, but Sitecore no longer recommends their use for headless projects.

https://community.sitecore.com/community?id=community_blog&sys_id=c0c103ea1b81bdd038a46421b24bcba9

In this case, I am not following any guidelines, but I wanted to show how the custom solution can be migrated and deployed from other than GitHub.

Create XM Cloud Project using the updated solution

The XM Cloud Deploy app can only connect to GitHub from the admin UI. It cannot connect to other source control platforms, such as Azure DevOps or Bitbucket. Therefore, to use Bitbucket, you must create your XM Cloud project using the CLI and upload your custom code once.

CLI Login

Create Project:

Please note the Project Id that you get it in the response. 

Create Environment: 

Please note the Environment Id that you get it in the response. 

Create Deployment with Upload Option

That's it. 

Next Steps:

Now the CM Cloud application is ready with the custom solution hosted in BitBucket. You can then setup CI/CD with Sitecore CLI and start managing your application source code from BitBucket itself. 

You can view my sample project in BitBuket here. 

XM Cloud: Sync Content between Environments

To sync content between XM Cloud Environments, SCS (Sitecore Content Serialization) is the preferred way when compared to old way of moving content using Sitecore Content Packages. In this article, we will move content from one environment to another by an easy way. 

Scenario: 

Two environments: DEV and PROD
Content Sync: Copy from PROD to DEV or Copy from PROD to Local
Content to be copied:

• /sitecore/content/samplesite/samplesite/Home
• /sitecore/content/samplesite/samplesite/Data

Sitecore Content Serialization (SCS) is a system for serializing, sharing, and deploying content items, as well as keeping them in version control.

Ref: https://doc.sitecore.com/xmc/en/developers/xm-cloud/sitecore-content-serialization.html

The flow is to connect to PROD, DEV and Local (if planning to sync it to local) environment using CLI connect command and then use CLI serialization command to pull from source Environment to target Environment. 

Step 1: Connect to Environments

Before we connect to XM Cloud Environments, it is important that Sitecore CLI with plugins are installed. XM Cloud Environment IDs are needed to connect. Use CLI connect command with --allow-write flag to enable read/write access for environments. 

PROD ID: 1rg2Cn4Nz9HlMvJDoMlp0R
DEV ID: 5uQrDqtEeitxTlNdOCTmwM

Step 2: Add Serialization Module to Content Sync Purpose

In order to sync only a specific set of content, it is optional to create a separate serialization module json file. In our scenario, we are pulling only the pages and the data folder. Create a module json with the below includes. 

Step 3: Pull Content from Source Environment

Using CLI Serialization command, pull the content by targeting only our content sync module. 

Step 4: Push Content to Target Environment

That's it. 

Every data is pulled and pushed via APIs. Copying huge number of items or bigger size media files may delay the sync process. 

XM Cloud CLI Plugin Commands

Summarized all the Sitecore CLI XM Cloud Plugin Commands, Subcommands and a sample execution command in the cheatography. Can be useful for the certification. 

Here is the link for the cheatography. 

https://cheatography.com/nehem87/cheat-sheets/sitecore-xm-cloud-cli-commands-list/

Happy Learning !!!

XM Cloud - Deployment in Queue will be started immediately if an in-progress deployment is cancelled

In XM Cloud, with Cloud CLI, you can create and start a deployment with command dotnet sitecore cloud deployment create -id 8juVRTmGHaiaCy2Fyn56el. There is an another option to submit a deployment request but do not start automatically. This feature is not available from Cloud Portal as of 08/25/23. 

To create a deployment request and not start it immediately, you can execute the below command. 

dotnet sitecore cloud deployment create -id 8juVRTmGHaiaCy2Fyn56el --no-start

When --no-start option is used, a new deployment will be created and status will be in queued state. 

To start the deployment, you can run dotnet sitecore cloud deployment start -id <<deploymentId>>. 

Scenario: If there is an on-going deployment in XM Cloud and you schedule another deployment requuest with --no-start option for the future release and if for some reason, you cancel the on-going deployment, then the on-going deployment will be stopped but the queued deployment request will automatically start even though we have not executed the start request. This might have been designed in this way or may be a bug in XM Cloud Deployment job. Time to check with Sitecore support!!!

Update: Sitecore support confirmed that it is reproducible, and they are working on a fix. 

Next Update: We've been able to reproduce the scenario you reported and sought clarification from the product team regarding the observed behavior. Based on their response, this behavior is intended. Specifically, the --no-start option doesn't influence the deployment queue. If a running deployment is cancelled, completed, or fails, the next deployment in the queue will always be triggered. This functionality is by design.

In progress with one request is queued

Queued request started automatically if the previous deployment is cancelled

Sitecore CLI Installation Failure or Wrong Version Installed

Recently developers are facing issues when installing Sitecore CLI. Or it may install version 5.0.16 which is not released officially. 

PS C:\Project\Working\cli1> dotnet tool install --add-source=https://sitecore.myget.org/F/sc-packages/api/v3/index.json sitecore.cli
You can invoke the tool from this directory using the following commands: 'dotnet tool run sitecore' or 'dotnet sitecore'.
Tool 'sitecore.cli' (version '5.0.16') was successfully installed. Entry is added to the manifest file C:\Project\Working\cli1\.config\dotnet-tools.json.

error NU1202: Package sitecore.cli 5.0.16 is not compatible with netcoreapp3.1 (.NETCoreApp,Version=v3.1) / any. Package sitecore.cli 5.0.16 supports: net6.0 (.NETCoreApp,Version=v6.0) / any
The tool package could not be restored.
Tool 'sitecore.cli' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET Core tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

Sitecore Official release version for Sitecore CLI as of July 7th 2022 is 4.2.1. Unofficially Sitecore published Sitecore CLI 5.0 as they are testing the new features. 

Anyone who installs Sitecore CLI without a specific version will get v5.0. Add version parameter to install the specific version to avoid this issue. 

dotnet tool install --add-source=https://sitecore.myget.org/F/sc-packages/api/v3/index.json sitecore.cli --version 4.2.1

Create, package and publish a Sitecore CLI Plugin

We (SitecoreWarriors) had a chance to participate in Sitecore Hackathon 2022 and we peeked into how the Sitecore's official plugins are created and how a new plugin can be created using Extensibility package provided by Sitecore. In this article, I wanted to explain few steps to create a new plugin, package it and publish it to nuget.org or any other private package manager. 

1. Create Plugin Project - .NET Core Class Library
2. Create Management Service - .NET Framework 4.8 Class Library
3. Package and Publish Plugin 

Create Plugin Project

• In order to create a plugin, we need to create a .NET Core Class Library. 
• Project type should be Microsoft.NET.Sdk. 
• From Sitecore Package source, add the following packages.
  
  
  
  
  
• Sitecore.Devex.Client.Cli.Extensibility
• This package helps to create an extension to the Sitecore CLI
• Adds base for SubCommand options
• Sitecore.DevEx.Serialization.Client
• Enables us to use SitecoreApiClient which helps to send and receive response from Sitecore through management service. 
• Helps to generate the API request along with access token and send it to Sitecore. 
• Not sure why but Sitecore may move this piece out of Serialization Client package and create it as a standalone package to avoid this dependency.
• Next step is to implement ISitecoreCliExtension interface which will let us to register Commands. As part of this sample application, we are trying to create a Job plugin which can retrieve the jobs list from Sitecore. 
  
  
  
• Then we can create new SubCommand class inheriting SubcommandBase from Sitecore.Devex.Client.Cli.Extensibility package. This will let us to override the handle method to implement the logic to call Sitecore API for this SubCommand.
  
  
  

• In the SubCommand implementation, use SitecoreApiClient and trigger the request to Sitecore Management API.  
  
  
  

Create Management Service

• Sitecore Management Service gets the request from CLI and execute the request in Sitecore Context. 
• Authentication token obtained from CLI login is sent as part of the Bearer token. 
• Depending upon the solution, the dependencies changes. In this case, we needed Sitecore.Kernel, Sitecore.DependencyInjection package. 
• Management services uses GraphQL. Queries and Mutations.
  
  Queries are the GraphQL equivalent to GET calls in REST. mutations represent the state-changing methods in REST (like DELETE, PUT, PATCH, etc).
  
  
• In this example, we are just getting Jobs list. So we can go with query. Implement Sitecore.Services.GraphQL.Schemas.SchemaProviderBase from Sitecore.Services.GraphQL and override CreateRootQueries which in turn returns the data to be returned to CLI. Logic is get the jobs list from JobManager and return the results. 
  
  
  

• Build the class library along with configuration and package it as Sitecore Package to be installed via Installation Wizard. 

Package and Publish Plugin

We can create package 

• using nuget.exe CLI. 
• using NuGet Package Explorer GUI. 

In this article, I will explain how we can package it using NuGet Package Explorer.

• We need to prepare the package content. Package should have the plugin library (.dll). Please note that DLL name and the plugin name should match otherwise we may get errors. Refer this article for more details - Sitecore CLI Extension Development - Possible errors and solution. 
• Once the NuGet Package Explorer is downloaded and opened, choose Create a new package. 
  
  
  
  
  
• Go to Edit menu and click Edit Metadata. 
• Add the plugin name in the ID field
• Create a new folder called plugin
• Add plugin class library and few other assemblies like Sitecore.DevEx.Serialization.Client and Microsoft.Extensions.Http to the plugin folder. 

• Go to nuget.org, create a new account, login to the account, click on your username and go to API keys. 
  
  
  
  
  
• Create a new API key. Provide a key name and click create. Copy the generated key and save it securely. 
  
  
  
  
  
• Go back to the NuGet package explorer, go to File and click Publish. Enter the copied API key in the Publish Key or PAT field and then click publish. It should be published immediately and it may take 10 minutes for the package to be available in the nuget.org search results. 
  
  
  
  
  
  
  
  
  

How to install the plugin and use it

• Install the management service package created in the second step in Sitecore CM using installation wizard. 
• Once the package is available in nuget.org search results, you can login to CLI using dotnet sitecore login. 
• Install the plugin using dotnet sitecore plugin add -n SitecorePlugin.Custom and plugin will be installed in your workstation. 
  
  
  

You can refer our Hackathon submission here.  

Sitecore CLI - Authentication and Authorization

Sitecore has a very good documentation on Authentication and Authorization. As stated, there are two flows. 

1. Interactive User Login
• Sitecore Username and Password are needed. 
• Used mostly by the developers.
2. Non-Interactive Client Login
• Client ID and Client Secret are needed. 
• Client should be configured in Identity server and Identity provider should be configured in Content Management as documented. 
• Used for CI/CD process to automate tasks.

In both the flows,  

• Identity server is must. 
• The result of the authentication and authorization is access token. If we wanted extended expiry of tokens for a longer running process, we can opt for refresh token. 

When we initiate the interactive login request using dotnet sitecore login --authority https://id.sitecorewarriors.localhost/ --cm https://cm.sitecorewarriors.localhost --allow-write true, Sitecore ID login screen will appear. Once logged in, we will get two options. 

Offline Access will generate refresh token along with short lived access token. A refresh token is a credential artifact that lets a client application get new access tokens without having to ask the user to log in again.

.sitecore/user.json file will be populated with the access token and refresh token. So we should not commit the .sitecore/user.json file to source control as it contains sensitive information.

Sitecore CLI Extension Development - Possible errors and solution

While we (Sitecore Warriors) were working on creating Sitecore CLI extension in Sitecore Hackathon, we came across few errors and I would like to share it in this article. 

• Could not locate plugin SitecoreWarriors.DevEx.Extensibility.Jobs@4.1.1. Some CLI commands may not function correctly.
  
  To speed up the development and testing the plugin, we can manually place the plugin assembly in /.sitecore/package-cache/nuget/PluginName and add the plugin name in the sitecore.json file. 
  
  
  
  
  Possible Reason 1: If the assembly name and plugin name do not match, then we will get this error. Once we set the same name for plugin as well the assembly name, the dotnet sitecore -h command will list the plugin. 
  
  Possible Reason 2: If the nuget package or the plugin assembly is not placed inside a folder called plugin, you will get this error. 
  
  
  
  
  

  PS C:\Project\Working\CLI> dotnet sitecore -h
  >> Begin installing NuGet packages: SitecoreWarriors.DevEx.Extensibility.Jobs@4.1.1
  >>> Skipping NuGet package SitecoreWarriors.DevEx.Extensibility.Jobs@4.1.1 because it is already installed.
  Could not locate plugin SitecoreWarriors.DevEx.Extensibility.Jobs@4.1.1. Some CLI commands may not function correctly.

  
  
• Plugin does not supported by the current version of the CLI. Please try to update you CLI
  
  Plugin product should be .NET Core project. If the plugin assembly project is created as a Web SDK (Microsoft.NET.Sdk.Web) project instead of just an SDK project, CLI will not be able to recognize the plugin. Make sure the project type is Microsoft.NET.Sdk. 
  
  
  
  
  

Job Plugin - Sitecore CLI Plugin - Sitecore Hackathon 2022

Sitecore Hackathon is a community driven event and we (Sitecore Warriors) chose idea Extend Sitecore CLI.

We chose many ideas and finally ended up completing Job related plugin. 

This Sitecore Job plugin will enable developers/admins to

1. View currently running, queued and finished jobs. Also lists configured Sitecore Database jobs.
2. Execute Sitecore Database jobs on-demand
3. Rebuild the Link database

There are two parts in developing a Sitecore CLI Plugin. 

1. Plugin (published in nuget.org)
2. Sitecore Management Service to initiate the action in Sitecore Context.

Installation instructions:

1. Sitecore instance (10.2) with Sitecore Management Services package installed. Setup a project folder in your workstation. Install and initiate the Sitecore CLI as mentioned in this document. 
2. As part of this job plugin, we have created a management service which can receive the request from the CLI and execute the action in Sitecore. The management service package is placed here. This package can be installed using Sitecore Installation Wizard. 
3. To install the job plugin, Sitecore has provided a plugin called plugin. You can pass on the plugin name along with add subcommand. Please note that this plugin is already published to nuget.org here. 
   dotnet sitecore plugin add -n SitecoreWarriors.DevEx.Extensibility.Jobs
4. To verify whether job plugin has been installed successfully, you can run dotnet sitecore job -h. 

Usage:

dotnet sitecore job [subcommand] [options]

Subcommands:

You can use the following subcommands:

1. list - Get all jobs list (running, queued, finished and db task jobs). Db task can be started on-demand.
2. rebuildlinkdb - Start rebuilding a link db.
3. start - Start a DB task.

Options:

You can use the following options with the list subcommand:

Option	Explanation
-c, --config (config)	Path to root sitecore.json directory (default: cwd)
-v, --verbose	Write some additional diagnostic and performance data
-t, --trace	Write more additional diagnostic and performance data
-?, -h, --help	Show help and usage information

You can use the following options with the start subcommand:

Option	Explanation
-c, --config (config)	Path to root sitecore.json directory (default: cwd)
-j, --job-name (job-name)	Mention DB Task Schedule Name from Listing.
-v, --verbose	Write some additional diagnostic and performance data
-t, --trace	Write more additional diagnostic and performance data
-?, -h, --help	Show help and usage information

You can use the following options with the rebuildlinkdb subcommand:

Option	Explanation
-c, --config (config)	Path to root sitecore.json directory (default: cwd)
-db, --database (database)	Mention DB name for rebuilding the link DB (default: master)
-v, --verbose	Write some additional diagnostic and performance data
-t, --trace	Write more additional diagnostic and performance data
-?, -h, --help	Show help and usage information

Demo:

• Install the job Sitecore management service package. 
• In order for Sitecore CLI to interact with Sitecore Management Services, we need to login and obtain the access token. 

dotnet sitecore login

• Install the job plugin.  
  dotnet sitecore plugin add -n SitecoreWarriors.DevEx.Extensibility.Jobs
  
  
  
  
  
• Get the list of commands in job plugin.  
  dotnet sitecore job -h
  
  
  
  
  
• To view the list of running, queued, finished and DB tasks.  
  dotnet sitecore job list
  
  
  
  
  
• To start a DB task. The last run changes once the job gets executed.
  dotnet sitecore job start -j {JobName}
  
  
  
  
  
• To rebuild the link database.
  dotnet sitecore job rebuildlinkdb -db master
  
  
  

Sitecore CLI is a powerful tool to automate admin tasks and integrate it as part of DevOps. Since additional plugins can be added easily, this tool can integrate not only with Sitecore XM/XP, it can be leveraged for other Sitecore product family with few customization.