The CLI serialization command

The info subcommand

The info command provides information about how the solution is set up and configured for use as it relates to content serialization.

The information returned by the command includes a list of all serialization module configurations. For every serialization module configuration, the information includes:

• Module name.
• Module description.
• Item subtrees with name and path.

You can use the following options with the info subcommand:

The following is an example of using the info subcommand:

dotnet sitecore ser info

\> sitecore ser info

Maximum subtree-relative item path allowed: 100

Feature.BasicContent
  Subtrees:
    templates: /sitecore/templates/Feature/BasicContent
    renderings: /sitecore/layout/Renderings/Feature/BasicContent
    buttons: core:/sitecore/content/Applications/WebEdit/Custom Experience Buttons/BasicContent
      FieldsFilter Excludes: 0
  Roles: 0

# ...

Project.DemoContent
An example of separating content into a separate module, so it can be excluded from deploy.
  Subtrees:
    content: /sitecore/content/Basic Company
    media: /sitecore/media library/Basic Company
      FieldsFilter Excludes: 1
  Roles: 0

Excluded Fields From Default Serialization Config:
      FieldsFilter Excludes: 1

The explain subcommand

You can use the explain to provide detailed serialization-related information on a given Sitecore item path and an optional database.

The subcommand provides the following:

• Item path is within the scope of any serialization modules.
• Related allowed operations for the given item path.
• Path to the serialization Module.json set up for the given path.

You can use the following options with the explain subcommand:

The following are examples of using the explain subcommand:

• Explain a path not included in any module configuration:

  shell

  dotnet sitecore ser explain --path "NOT_INCLUDED_PATH"

  Output:

  shell

  Path master:NOT_INCLUDED_PATH is not included in any module configuration.

• Explain a path included in a module configuration:

  shell

  dotnet sitecore ser explain --path "INCLUDED_PATH"

  Output:

  shell

  [MODULE_NAME] [INCLUDED_PATH] Item path matches subtree scope ItemAndDescendants.
  [MODULE_NAME] [INCLUDED_PATH] Subtree set allowed push operations CreateUpdateAndDelete
  [MODULE_NAME] [INCLUDED_PATH] Path master:INCLUDED_PATH is included!
  Physical path:PATH_TO_YAML_FILE

The pull subcommand

The pull subcommand takes items from Sitecore, serializes them, and stores them as .yml files on a given file system path. The subcommand uses Module.json files to determine what items are included in the serialization process. During the pull operation, the serialization engine evaluates existing serialized items on disk and performs a deep comparison of the same items in the source Sitecore instance.

This command requires elevated permissions.

You can use the following options with the pull subcommand:

The following are examples of using the pull subcommand:

• Serialize all sitecore items from the configurations:

  shell

  dotnet sitecore ser pull

• Serialize all Sitecore items from the ModuleA and ModuleB configurations:

  shell

  dotnet sitecore ser pull -i ModuleA ModuleB

• Serialize all Sitecore items from the modules tagged as tagA and tagB configurations:

  shell

  dotnet sitecore ser pull -i tags:[tagA,tagB]

• Serialize all items from the modules tagged as tagA, tagB, and ModuleA configurations:

  shell

  dotnet sitecore ser pull -i tags:[tagA,tagB] ModuleA

The push subcommand

The push command takes items serialized as .yml files on disk and pushes them to a destination Sitecore instance. The push operation uses serialization Module.json files to determine the items included in the serialization process. During the push operation, the serialization engine evaluates existing serialized items on the file system and performs a deep comparison of the same Items in the source Sitecore instance.

This command requires elevated permissions.

You can use the following options with the push subcommand:

The following are examples of using the push subcommand:

• Push all Sitecore items from the configuration to the Sitecore instance:

  shell

  dotnet sitecore ser push

• Push all Sitecore items from the ModuleA and ModuleB configurations to the Sitecore instance:

  shell

  dotnet sitecore ser push -i ModuleA ModuleB

• Push all Sitecore items from the modules tagged as tagA and tagB configurations to the Sitecore instance:

  shell

  dotnet sitecore ser push -i tags:[tagA,tagB]

• Push all Sitecore items from the modules tagged as tagA, tagB, and ModuleA configurations to the Sitecore instance:

  shell

  dotnet sitecore ser push -i tags:[tagA,tagB] ModuleA

The diff subcommand

The diff subcommand compares serialization items between a source Sitecore instance and a destination Sitecore instance. The operation uses serialization Module.json files to determine the items included in the comparison process. During the diff command, the serialization engine performs a deep comparison of paths and items in the source Sitecore instance and the destination Sitecore instance.

This command requires elevated permissions in both source and target environments.

To use the diff subcommand, you must log in to both the source and destination environments using client credentials, which will generate access tokens for each environment. If you don't log in to both environments, running the command will result in a missing access token error.

You can log in to each environment and automatically generate the necessary access tokens in the .sitecore/user.json file using the following command:

dotnet sitecore login \\
  --authority https://auth.sitecorecloud.io/ \\
  --cm https://<ENVIRONMENT_HOST_NAME> \\
  --audience https://api.sitecorecloud.io \\
  --client-credentials true \\
  --client-id <ENVIRONMENT_CLIENT_ID> \\
  --client-secret <ENVIRONMENT_CLIENT_SECRET> \\
  --allow-write true \\
  -n "<ENVIRONMENT_NAME>"

Replace the environment name and host name with the actual environment values in the Deploy app, and the client ID and client secret with your actual client credentials.

You can use the following options with the diff subcommand:

The following is an example of using the diff subcommand:

dotnet sitecore ser diff -s SOURCE -d DESTINATION

Output:

[DBNAME] Discovered CHANGES_COUNT changes after evaluating ITEMS_COUNT total items.

The validate subcommand

The validate subcommand ensures file system integrity of serialized items and paths. Additionally, by using the --fix (-f) argument option flag, the command can attempt to auto-correct identified issues. The subcommand evaluates all serialized paths and subtrees on the file system configured in serialization Module.json files and performs the following checks on the file system:

• Invalid physical path.
• Orphaned parent ID.
• Non-included item.
• Empty folder.
• Duplicate item ID.
• Non-unique path.

You can use the following options with the validate subcommand:

The following are examples of using the validate subcommand:

• Read-only validation:

  shell

  dotnet sitecore ser validate

  Output:

  shell

  Read-only validation is active. No fixes will be made.
  No errors were detected.

• Vaidate and fix:

  shell

  dotnet sitecore ser validate --fix

  Output:

  shell

  DUPLICATE ID: 5c069416-660c-4028-b5c8-c9f3ce3cb277 found in ...
  [D] ~\\FILE_DUPLICATE.yml
  ...
  No errors were detected.

The watch subcommand

The watch subcommand monitors changes to content items in a Sitecore instance and automatically serializes the changes to your file system.

This command requires elevated permissions.

You can use the following options with the watch subcommand:

The following is an example of using the watch subcommand:

dotnet sitecore ser watch

Output:

Watcher is online! Changes made to serialized items will be automatically pulled.

The package subcommand

The package subcommand (short form pkg) provides additional subcommands for package specific operations, as follows:

You can use the following options with the package subcommand:

The package create subcommand

The package create subcommand creates a new serialized item package.

You can use the following options with the package create subcommand:

The following are examples of using the package create subcommand:

• Create a package at a specified file path:

  shell

  dotnet sitecore ser pkg create -o <file-path>

• Serialize a module with roles:

  json

  {
      "namespace": "Feature.Products",
      "roles": [
          {
              "domain": "DevEx",
              "pattern": "Product"
          }
      ]
  }

  shell

  dotnet sitecore ser info --include Feature.Products -v

  Output:

  shell

  [role] [A] Role DevEx\\Product Admin is created successfully.
  [role] [A] Role DevEx\\Product Merchandiser is created successfully.
  [roles] Synced 2 roles completed.

The package install subcommand

The package install subcommand installs an existing item package to Sitecore.

This command requires elevated permissions.

You can use the following options with the package install subcommand:

The following is an example of using the package install subcommand to install a package using the file path to the Sitecore instance:

dotnet sitecore ser pkg install -f <file-path>