---
title: "The CLI serialization command"
slug: "the-cli-serialization-command"
abstract: "Reference for the Sitecore CLI serialization command that serializes items."
---
# The CLI serialization command

The Sitecore serialization plugin provides the `serialization` command with the short form `ser`.

This command handles the serialization of items.

To install the serialization plugin, run the following code:

```text
dotnet sitecore plugin add -n Sitecore.DevEx.Extensibility.Serialization

```

## Usage

You can use the command as follows:

```text
dotnet sitecore serialization [subcommand] [options]

```

Alternatively, you can use the short form for the command as follows:

```text
dotnet sitecore ser [subcommand] [options]

```

## Subcommands

You can use the following subcommands:

- The [`info` subcommand](https://doc.sitecore.com/xp/en/developers/101/developer-tools/the-cli-serialization-command.html#UUID-a0794c45-7d08-d440-7bff-416610cc2c71_section-idm4556665106350432792957280148 "The info subcommand") - shows serialization configuration information.
- The [`explain` subcommand](https://doc.sitecore.com/xp/en/developers/101/developer-tools/the-cli-serialization-command.html#UUID-a0794c45-7d08-d440-7bff-416610cc2c71_section-idm4609582190612832792957138232 "The explain subcommand") - explains whether a content item path is included and why.
- The [`pull` subcommand](https://doc.sitecore.com/xp/en/developers/101/developer-tools/the-cli-serialization-command.html#UUID-a0794c45-7d08-d440-7bff-416610cc2c71_section-idm4609582433057632792957482901 "The pull subcommand") - serializes content items from a Sitecore instance to your file system.
- The [`push` subcommand](https://doc.sitecore.com/xp/en/developers/101/developer-tools/the-cli-serialization-command.html#UUID-a0794c45-7d08-d440-7bff-416610cc2c71_section-idm4544533837987232792957859689 "The push subcommand") - pushes serialized content items from your file system to a Sitecore instance.
- The [`diff` subcommand](https://doc.sitecore.com/xp/en/developers/101/developer-tools/the-cli-serialization-command.html#UUID-a0794c45-7d08-d440-7bff-416610cc2c71_section-idm4556665117923232792958045556 "The diff subcommand") - compares the content items of two Sitecore instances.
- The [`validate` subcommand](https://doc.sitecore.com/xp/en/developers/101/developer-tools/the-cli-serialization-command.html#UUID-a0794c45-7d08-d440-7bff-416610cc2c71_section-idm4609582154825632792957760524 "The validate subcommand") - checks serialized content items for validity. Can fix common issues with the `--fix` argument.
- The [`watch` subcommand](https://doc.sitecore.com/xp/en/developers/101/developer-tools/the-cli-serialization-command.html#UUID-a0794c45-7d08-d440-7bff-416610cc2c71_section-idm455665573495363279295823451 "The watch subcommand") - monitors changes to content items in a Sitecore instance and automatically serializes the changes to your file system.
- The [`package` subcommand](https://doc.sitecore.com/xp/en/developers/101/developer-tools/the-cli-serialization-command.html#UUID-a0794c45-7d08-d440-7bff-416610cc2c71_section-idm4556665033134432792958335354 "The package subcommand") - provides additional commands for working packages of serialized items.
- The [`package create` subcommand](https://doc.sitecore.com/xp/en/developers/101/developer-tools/the-cli-serialization-command.html#UUID-a0794c45-7d08-d440-7bff-416610cc2c71_section-idm4556665402577632792958434819 "The package create subcommand") - creates a package of serialized items.
- The [`package install` subcommand](https://doc.sitecore.com/xp/en/developers/101/developer-tools/the-cli-serialization-command.html#UUID-a0794c45-7d08-d440-7bff-416610cc2c71_section-idm4609582163089632792958134581 "The package install subcommand") - installs a package of serialized items in a Sitecore instance.

Some subcommands have additional options or improvements to existing options starting with version 4.0.0, as follows:

- In version 4.0.0 and later, you can specify excluded fields with the `--exclude` (`-e`) option on most subcommands.
- In version 4.0.0 and later, the `push` subcommand supports the `--targets` (`-pt`) option.
- In version 4.1.0 and later, some subcommands support a `--force` (`-fr`) option that forces the operation to continue by skipping error-causing files, throwing a warning instead of an error. The option is available for version 4.1.0 and later.
- In version 4.1.0 and later, the `--include` (`-i`) and `--exclude` (`-e`) options support module tags. The subcommands `push` and `pull` also support tags.

<details>
<summary><h3>The info subcommand</h3></summary>

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:

| Option | Required? | Description |
| --- | --- | --- |
| `-i, --include <include>` | No | Specify module configurations to include. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-e, --exclude <exclude>` | No | Specify module configurations to exclude explicitly. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-c, --config <config>` | No | Path to root `sitecore.config` directory. Default: current working directory. |
| ` -v, --verbose` | No | Write additional diagnostic and performance data. |
| `-t, --trace` | No | Write additional diagnostic and performance data. |
| `-?, -h, --help` | No | Display developer help and usage information about the command. |

The following is an example of using the `info` subcommand:

- Command: Result
- 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

```

</details>

<details>
<summary><h3>The explain subcommand</h3></summary>

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:

| Option | Required? | Description |
| --- | --- | --- |
| `-p, --path <path>` | Yes | Item path to explain. |
| `-d, --database <database>` | No | Database of the item path to explain. Default: `master`. |
| `-c, --config <config>` | No | Path to root `sitecore.config` directory. Default: current working directory. |
| `-v, --verbose` | No | Write some additional diagnostic and performance data. |
| `-?, -h, --help` | No | Display developer help and usage information about the command. |

The following are examples of using the `explain` subcommand:

- Command: Result
- Explain a path not included in any module configuration:dotnet sitecore ser explain --path "NOT_INCLUDED_PATH":

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

```

- Explain a path included in a module configuration:dotnet sitecore ser explain --path "INCLUDED_PATH":

```

[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

```

</details>

<details>
<summary><h3>The pull subcommand</h3></summary>

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:

| Option | Required? | Description |
| --- | --- | --- |
| `-n, --environment-name <environment-name>` | No | Named Sitecore environment to use. Default: `'default'`; |
| `-i, --include <include>` | No | Specify module configurations to include. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-e, --exclude <exclude> ` | No | Specify module configurations to exclude explicitly. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-w, --what-if` | No | List the commands involved in the operation without running them.<br><br>> [!note]<br>> See the video [Sitecore CLI and the 'what-if' flag](https://www.youtube.com/watch?v=4fSN4nfwojI)for more information on the `-- what-if` option. |
| `-s, --skip-validation` | No | Skip filesystem integrity validation before syncing. |
| `-c, --config <config>` | No | Path to root `sitecore.config` directory. Default: current working directory. |
| `-v, --verbose` | No | Write additional diagnostic and performance data. |
| `-t, --trace` | No | Write additional diagnostic and performance data. |
| `-fr, --force` | No | Show a warning instead of an error. Skip the item causing the warning and continue serialization. |
| `--use-debug-signatures` | No | Use debug (un-hashed) item signatures to diagnose hash mismatches. Much slower. |
| `-?, -h, --help` | No | Display developer help and usage information about the command. |

The following are examples of using the `pull` subcommand:

- Command: Result
- dotnet sitecore ser pull: All Sitecore items from the configurations are serialized on disk.
- dotnet sitecore ser pull -i ModuleA ModuleB: All Sitecore items from the ModuleA and ModuleB configurations are serialized on disk.
- dotnet sitecore ser pull -i tags:[tagA,tagB]: All Sitecore items from the modules tagged as tagA and tagB configurations are serialized on disk.
- dotnet sitecore ser pull -i tags:[tagA,tagB] ModuleA: All Sitecore items from the modules tagged as tagA, tagB, and ModuleA configurations are serialized on disk.

</details>

<details>
<summary><h3>The push subcommand</h3></summary>

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:

| Option | Required? | Description |
| --- | --- | --- |
| `-n, --environment-name <environment-name>` | No | Named Sitecore environment to use. Default: `'default'`. |
| `-i, --include <include>` | No | Specify module configurations to include. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-e, --exclude <exclude>` | No | Specify module configurations to exclude explicitly. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-w, --what-if` | No | List the commands involved in the operation without running them. |
| `-s, --skip-validation` | No | Skip file system integrity validation before syncing. |
| `-c, --config <config>` | No | Path to root `sitecore.config` directory. Default: current working directory. |
| `-v, --verbose` | No | Write additional diagnostic and performance data. |
| `-t, --trace` | No | Write additional diagnostic and performance data. |
| `-fr, --force` | No | Show a warning instead of an error. Skip the item causing the warning and continue serialization. |
| `--use-debug-signatures` | No | Use debug (un-hashed) item signatures to diagnose hash mismatches. Much slower. |
| `-p, --publish` | No | Publish synced items. Not recommended to use with Publishing Service due to performance drop. |
| `--pt, --targets <targets>` | No | List of targets database to publish. Blank publishes to the `web` database. |
| `-?, -h, --help` | No | Display developer help and usage information about the command. |

The following are examples of using the `push` subcommand:

- Command: Result
- dotnet sitecore ser push: All Sitecore items from the configurations are pushed to the Sitecore instance.
- dotnet sitecore ser push -i ModuleA ModuleB: All Sitecore items from the ModuleA and ModuleB configurations are pushed to the Sitecore instance.
- dotnet sitecore ser push -i tags:[tagA,tagB]: All Sitecore items from the modules tagged as tagA and tagB configurations are pushed to the Sitecore instance.
- dotnet sitecore ser push -i tags:[tagA,tagB] ModuleA: All Sitecore items from the modules tagged as tagA, tagB, and ModuleA configurations are pushed to the Sitecore instance.

</details>

<details>
<summary><h3>The diff subcommand</h3></summary>

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.

You can use the following options with the `diff` subcommand:

| Option | Required? | Description |
| --- | --- | --- |
| `-s, --source <source>` | Yes | Named Sitecore endpoint to use as a source for comparison. |
| `-d, --destination <destination>` | Yes | Named Sitecore endpoint to use as a destination for comparison. |
| `-i, --include <include>` | No | Specify module configurations to include. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-e, --exclude <exclude>` | No | Specify module configurations to exclude explicitly. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-p, --path <path>` | No | Item path to compare (instead of include/exclude). |
| `--source-database <source-database>` | No | Source database (when used with `--path`). |
| `--destination-database <destination-database>` | No | Destination database (when used with `--path`). |
| `--push` | No | Apply the detected differences to the destination. |
| ` -c, --config <config>` | No | Path to the root `sitecore.config` directory. Default: current working directory. |
| `-v, --verbose` | No | Write additional diagnostic and performance data. |
| `-t, --trace` | No | Write additional diagnostic and performance data. |
| `-?, -h, --help` | No | Display developer help and usage information about the command. |

The following is an example of using the `diff` subcommand:

- Command: Result
- dotnet sitecore ser diff -s SOURCE -d DESTINATION:

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

```

</details>

<details>
<summary><h3>The validate subcommand</h3></summary>

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.

> [!note]
> For more information, see [Validate serialized content items](https://doc.sitecore.com/xp/en/developers/101/developer-tools/validate-serialized-content-items.html "Validate serialized content items").

You can use the following options with the `validate` subcommand:

| Option | Required? | Description |
| --- | --- | --- |
| `-i, --include <include>` | No | Specify module configurations to include. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-e, --exclude <exclude>` | No | Specify module configurations to exclude explicitly. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-f, --fix` | No | Execute possible fix operations when validating the serialized items.<br><br>> [!important]<br>> Using the `--fix (-f)` option can delete local files. |
| `-c, --config <config>` | No | Path to the root `sitecore.config` directory. Default: current working directory. |
| `-v, --verbose` | No | Write additional diagnostic and performance data. |
| `-t, --trace` | No | Write additional diagnostic and performance data. |
| `-?, -h, --help` | No | Display developer help and usage information about the command. |

The following is an example of using the `validate` subcommand:

- Command: Result
- dotnet sitecore ser validate:

```

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

```

- dotnet sitecore ser validate --fix:

```

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

```

</details>

<details>
<summary><h3>The watch subcommand</h3></summary>

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:

| Option | Required? | Description |
| --- | --- | --- |
| `-n, --environment-name <environment-name>` | No | Named Sitecore environment to use. Default: 'default'; |
| `-i, --include <include>` | No | Specify module configurations to include. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-e, --exclude <exclude>` | No | Specify module configurations to exclude explicitly. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-s, --skip-pull` | No | Skip pulling data from Sitecore before starting the watcher. |
| `--allow-file-changes` | No | Continue watching files if they change.<br><br>> [!important]<br>> Using this option can result in tree corruption if the underlying state is changed.<br>> Use this option only if some other program touches serialized files that are not changing. |
| `-fr, --force` | No | Show a warning instead of an error. Skip the item causing the warning and continue serialization. |
| `-c, --config <config>` | No | Path to the root `sitecore.config` directory. Default: current working directory. |
| `-v, --verbose` | No | Write additional diagnostic and performance data. |
| `-t, --trace` | No | Write additional diagnostic and performance data. |
| `-?, -h, --help` | No | Display developer help and usage information about the command. |

The following is an example of using the `watch` subcommand:

- Command: Result
- dotnet sitecore ser watch:

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

```

</details>

<details>
<summary><h3>The package subcommand</h3></summary>

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

| Subcommand | Description |
| --- | --- |
| `create` | Creates a new serialized item package. |
| `install` | Install an existing item package to Sitecore.<br><br>This command requires elevated permissions. |

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

|  |  |
| --- | --- |
| `-?, -h, --help` | Display developer help and usage information about the command. |

</details>

<details>
<summary><h3>The package create subcommand</h3></summary>

The `package create` subcommand creates a new serialized item package.

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

| Option | Required? | Description |
| --- | --- | --- |
| `-o, --output <output>` | Yes | Path for placing the package after creation. If you do not provide an extension, it is added for you. |
| `--overwrite` | No | Allow overwriting an existing package. |
| `-i, --include <include>` | No | Specify module configurations to include. Supports module name, tags. Wildcards and multiple values are allowed. From version 4.1.0 and later, `roles` specified in a Serialization Module are also serialized. |
| `-e, --exclude <exclude>` | No | Specify module configurations to exclude explicitly. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-c, --config <config>` | No | Path to the root `sitecore.config` directory. Default: current working directory. |
| `-v, --verbose` | No | Write additional diagnostic and performance data. |
| `-t, --trace` | No | Write additional diagnostic and performance data. |
| `-?, -h, --help` | No | Display developer help and usage information about the command. |

The following is an example of using the `package create` subcommand:

- Command: Result
- dotnet sitecore ser pkg create -o FILE_PATH: A package was created at the specified `FILE_PATH`.
- Serializing a module with roles:{
    "namespace": "Feature.Products",
    "roles": [
        {
            "domain": "DevEx",
            "pattern": "Product"
        }
    ]
}dotnet sitecore ser info --include Feature.Products -v: Output:

```

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

```

</details>

<details>
<summary><h3>The package install subcommand</h3></summary>

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:

| Option | Required? | Description |
| --- | --- | --- |
| `-f, --package <package>` | Yes | Path to the package to install. |
| `--auth, --authority <authority>` | No | Identity authority for the environment, such as identity server or AAD tenant URL. |
| `--cm <cm>` | No | Sitecore content management hostname to connect to. |
| `--client-id <client-id>` | No | The OAuth ClientID to send. Defaults to `'Device'` for device auth and `'SitecoreCLIServer'` for client credentials. |
| `--client-secret <client-secret>` | No | The OAuth ClientID to send. Defaults to `'Device'` for device auth and `'SitecoreCLIServer'` for client credentials. |
| `-n, --environment-name <environment-name>` | No | Named Sitecore environment to use. Default: `'default'`. |
| `-w, --what-if` | No | List the commands involved in the operation without running them. |
| `-i, --include <include>` | No | Specify module configurations to include. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-e, --exclude <exclude>` | No | Specify module configurations to exclude explicitly. Supports module name, tags. Wildcards and multiple values are allowed. |
| `-c, --config <config>` | No | Path to root `sitecore.config` directory. Default: current working directory. |
| `-v, --verbose` | No | Write additional diagnostic and performance data. |
| `-t, --trace` | No | Write additional diagnostic and performance data. |
| `-p, --publish` | No | Publish synced items.<br><br>Because of performance concerns, we recommend you avoid using this option with the Publishing Service. |
| `-?, -h, --help` | No | Displays developer help and usage information about the command. |

The following is an example of using the `package install` subcommand:

- Command: Result
- dotnet sitecore ser pkg install -f FILE_PATH: The package `FILE_PATH` was installed to the Sitecore instance.

</details>