#Sitecore CLI for the Curious

Today’s post relates to [the 04-RunningSMSCommands branch or later](https://github.com/gillissm/TheCodeAttic.Learning.SitecoreHeadless/tree/04-runningsmscommands) starting at this point all the required module JSON files will exist and be tied to items for syncing.

With the initial pull of the codebase, you will need to initialize the Sitecore CLI tooling for the solution. This is done by opening a PowerShell prompt as Admin and navigating to the directory that the *sitecore.json* configuration file is found. In many solutions this will be at the root of the solution code, for the sample Rainfly Tours codebase you will want to go to  **<Project Directory>/RainflyTours/src/platform**.

Once at this location you will need to run the command

dotnet tool restore

This will restore (download) the required CLI version for the site solution. On the next command you run installation will complete by downloading the defined plugins for the CLI. I like running one of the following immediately, so I do not have to wait when it comes time to work.

# See the list of commands
dotnet sitecore -h

# OR see the list of plugins for this install
dotnet sitecore plugin list

You have probably already noticed, but to interact with the sitecore CLI, you must preface with dotnet.

Establishing Authorization to Interact with the Environment

With tooling in place, the next thing to do is establish the connection between the CLI and you Sitecore instance. Working from the same PowerShell prompt as above you will need to leverage the login plugin, running

dotnet sitecore login `
   --authority https://id.rainflytours.com # full URL to the identity server
   --cm https://cm.rainflytours.com # full URL to the CM server
   --allow-write true # flag that takes true or false, indicating if the current connection can write into the Sitecore instance, writing is required to sync item data into the environment

A browser tab will open prompting you to enter credentials. Upon successful entering of credentials, you will be asked to confirm the grant of permissions for the CLI to use, accept all for now. With the successful completion of authenticating and authorizing the CLI, the user.json configuration file found in ‘.sitecore’ directory contains the require information for successful future use, saving the need to re-login every time a command is desired.

Look at the Serialization Plugin (ser)

The plugin that will be used most often during the development process is the Serialization or ser plugin. This plugin is all about providing ways to serialize your content for tracking in source control, while also providing ways to move that same content into other environments.

(The following highlights are based on the Sitecore CLI version 5.0.16, newer, as well as older, versions may have additional commands I have not noted here, be sure to always check the latest documentation for you version for full feature capabilities.)

One of the first commands I like to run after getting latest code or completing configuration for a module is info.

dotnet sitecore info

This command scans the solution for module JSON files and then displays a tree view of items that are being tracked for serialization. If errors exist, you will be notified of this as well.

After having an understanding of what is in the project and knowing the state of the target environment (because of its usage of APIs the next few moves will work against even remote environments) we should leverage the push command to get in sync with source.

dotnet sitecore ser push

Leveraging push with no parameters will move all the serialized content to the default configured environment, this is normally the local developer environment. Where things start to get powerful is through the usage of a handful off key parameters:

  • –environment-name or -n
    • target environment from as found in the user.json configuration file found in the .sitecore directory.
  • –include or -i
    • this parameter requires a comma delimited list of specific module names that should be pushed, you can even use the asterisk wildcard to allow for multiple modules to be pushed
  • –exclude or -e
    • similar to the include, this provides a mechanism to ensure things do NOT push to the environment
  • –publish or -p
    • Once the sync completes this will perform a publish of those items

Leveraging the same set of parameters is the pull command, which allows the defined content from the target environment to be serialized, overwriting any pre-existing serialized data.

During times of heavy development work, you may not want to worry about pulling down changes for serialization, for those periods of work you can leverage the watch command. It to uses the same set of parameters as defined for push.

Finally, a super helpful command for those times you are troubleshooting or just need to perform some content refreshing there exists the *diff command.

This adds two additional key parameters to the above list:

  • –source or -s
    • environment that changes are pulled from as defined in the user.json configuration
  • –destination or -d
    • environment that changes should be pushed into as defined in the user.json configuration dotnet
  • –push
    • include this parameter flag to push any changes from the source environment up to the destination

Simplify Publishing and Indexing with the CLI

To further enhance the opportunities to manage a site from the command line (or really more importantly through a CI/CD process) there exists plugins for publishing as well as indexing.

The publishing plugin is fairly simple leveraging the following parameters

  • –environment-name or -n
    • target environment as found in the user.json configuration file found in the .sitecore directory, if not provided will use the ‘default’ environment as the target to act on
  • –path or -p
    • provide an item path or GUID to indicate which portion of the content tree should be published, if not declared the entire tree will be published
  • –republish or -r
    • include this flag to force a republish of the defined content, otherwise publishing will be smart-publish
  • –targets or –pt
    • comma delimited list of publishing targets that should be published to, if not included the web will be the target
dotnet sitecore publish -n rainclouds --path /sitecore/content/rainflytours/Home

Publishing content is always nice, but how about the ability to perform some index maintenance as well. The index plugin provides access to perform basic actions against the index.

First, command which caught my eye was statistic which provides a listing of the key metrics around all or a specific index in the target environment.

Also included is the ability to rebuild all or named indexes.

There is a lot of power available in the Sitecore CLI, and this article provides just a quick review of some of the key commands that your team can take advantage of.



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.