1. Sitecore CLI command reference

The CLI itemres command

The Sitecore Items as Resources plugin includes an itemres command. This command creates an item package in a resource file with configurable options.

To install the Items as Resources plugin, run the following code:

bash
dotnet sitecore plugin add -n Sitecore.DevEx.Extensibility.ResourcePackage --version <version>

Usage

You can use the command as follows:

bash
dotnet sitecore itemres [subcommand] [options]

Subcommands

You can use the following subcommands:

  • create - creates a resource package.
  • unicorn - creates a Unicorn resource package.
  • cleanup - cleans up database items contained in .dat files if the item data in both entries are equal. This subcommand is available for CLI 4.1 or later.

The create subcommand

The create subcommand creates a new items and resources package. The CLI names the package based on the convention items.{databaseName}.{providedName}.dat.

You can use the following options with the create subcommand:

  • -o, --output <OUTPUT> - Required. Package path to output. The extension is added if not provided.
  • --overwrite <OVERWRITE> - Overwrite an existing package.
  • -i, --include <INCLUDE> - Include module configurations. Wildcards and multiple values are allowed.
  • -e, --exclude <EXCLUDE> - Explicitly exclude module configurations. Wildcards and multiple values are allowed.
  • -c, --config <CONFIG> - Path to the root sitecore.config directory. Default: current working directory.
  • -v, --verbose - Report additional diagnostic and performance data.
  • -t, --trace - Report additional diagnostic and performance data.
  • -?, -h, --help - Help for the command.

Examples:

Create a package that includes all modules

Command:

bash
dotnet sitecore itemres create -o TestPackage

Result: Creates the items.{databaseName}.TestPackage.dat file. The file includes all modules.

Create a package in a specific folder

Command:

bash
dotnet sitecore itemres create -o test/TestPackage

Result: Creates the items.{databaseName}.TestPackage.dat file in the test folder. The file includes all modules.

Duplicate package name without overwrite

Command:

bash
dotnet sitecore itemres create -o TestPackage

Result:

text
The output path items.{databaseName}.TestPackage.dat already existed, but Overwrite was false.

Duplicate package name with overwrite

Command:

bash
dotnet sitecore itemres create -o TestPackage --overwrite

Result: Creates and overwrites the package.

Include specific modules

Command:

bash
dotnet sitecore itemres create -o TestPackage -i Project.Content.Test

Result: Creates the package and includes only the Project.Content.Test module.

Command:

bash
dotnet sitecore itemres create -o TestPackage -i Project.Content.Test, Project.Content

Result: Creates the package and includes only the Project.Content.Test and Project.Content modules.

Include modules with wildcards

Command:

bash
dotnet sitecore itemres create -o TestPackage -i *Test

Result: Creates the package and includes only the Project.Content.Test module, found with a wildcard prefix.

Command:

bash
dotnet sitecore itemres create -o TestPackage -i *Test*

Result: Creates the package and includes only the Project.Content.Test and Project.Content.Test1 modules, found with surrounding wildcards.

Command:

bash
dotnet sitecore itemres create -o TestPackage -i Project*

Result: Creates the package and includes the Project.Content, Project.Content.Test, and Project.Content.Test1 modules, found with a wildcard suffix.

Exclude specific modules

Command:

bash
dotnet sitecore itemres create -o TestPackage -e Project.Content.Test

Result: Creates the package and includes only the Project.Content and Project.Content.Test1 modules, excluding the Project.Content.Test module.

Command:

bash
dotnet sitecore itemres create -o TestPackage -e Project.Content.Test, Project.Content

Result: Creates the package and includes only the Project.Content.Test1 module, excluding the Project.Content and Project.Content.Test modules.

Exclude modules with wildcards

Command:

bash
dotnet sitecore itemres create -o TestPackage -e *Test

Result: Creates the package and includes only the Project.Content and Project.Content.Test1 modules, excluding the Project.Content.Test module with a wildcard prefix.

Command:

bash
dotnet sitecore itemres create -o TestPackage -e *Test*

Result: Creates the package and includes only the Project.Content module, excluding the Project.Content.Test and Project.Content.Test1 modules with surrounding wildcards.

Command:

bash
dotnet sitecore itemres create -o TestPackage -e Project*

Result: Creates the package and excludes the Project.Content, Project.Content.Test, and Project.Content.Test1 modules with a wildcard suffix.

Combine include and exclude filters

Command:

bash
dotnet sitecore itemres create -o TestPackage -i Project* -e Project.Content.Test

Result: Creates the package and includes the Project.Content and Project.Content.Test1 modules with a wildcard suffix and excludes the Project.Content.Test module.

Command:

bash
dotnet sitecore itemres create -o TestPackage -i Project.Content.Test -e Project.Content.Test

Result:

text
The include and exclude options contain the same modules at the same time

Run from outside a Sitecore project

Command:

bash
dotnet sitecore itemres create -o TestPackage

Result:

text
error: Couldn't resolve a root configuration file (sitecore.json) in the current or any parent directory. Looks like the command might have been executed outside a Sitecore project?

Command:

bash
dotnet sitecore itemres create -o TestPackage -c Prototype/

Result: Creates the package in the samples folder.

Generate diagnostic output

Command:

bash
dotnet sitecore itemres create -o TestPackage -v

Result: Creates additional diagnostic and performance data, such as a root config path or count of nodes with performance, for example, 73ms (8.1ms/node).

Command:

bash
dotnet sitecore itemres create -o TestPackage -t

Result: Creates additional diagnostic and performance data, such as FSIndex: Loaded filesystem indices in, for example, 70ms (9 metadata), or created package of 1 trees in, for example, 1983ms (9 items; 220.3ms/node).

The unicorn subcommand

The unicorn subcommand creates a new items and resources package from Unicorn serialization with the specific name format items.{databaseName}.{providedName}.dat.

You can use the following options with the unicorn subcommand:

  • -p, --path <INCLUDE> - Required. Path to Unicorn serialization.
  • -o, --output <OUTPUT> - Required. Package path to output. The extension is added if not provided. Multiple values are allowed.
  • --overwrite <OVERWRITE> - Overwrite an existing package.
  • -c, --config <CONFIG> - Path to the root sitecore.config directory. Default: current working directory.
  • -v, --verbose - Report additional diagnostic and performance data.
  • -t, --trace - Report additional diagnostic and performance data.
  • -?, -h, --help - Help for the command.

Example:

Command:

bash
dotnet sitecore itemres unicorn -p "testItem" -o "TestPackage"

Result: Creates the items.{databaseName}.TestPackage.dat file.

The cleanup subcommand

The cleanup subcommand cleans up database items in .dat files if the item data in both entries are equal.

Warning

This command triggers a full cache cleanup, and it can cause performance degradation. It should be executed during a maintenance window.

You can use the following options with the cleanup subcommand:

  • -f, --force - Force items cleanup without field comparison. Available from version 5.1.28.
  • -w, --what-if - Simulate items cleanup without deleting items. Available from version 5.1.28.
  • -p, --path - Sitecore item path or GUID to clean up. Required for Sitecore 10.3 if using the --force or --what-if options.
  • -r, --recurse - Recursively clean up all items under the specified path.
  • -c, --config <CONFIG> - The path to the sitecore.json configuration file. Default: cwd.
  • -n, --environment-name <ENVIRONMENT_NAME> - Named Sitecore environment to use. Default: default.
  • -v, --verbose - Report additional diagnostic and performance data.
  • -t, --trace - Report additional diagnostic and performance data.
  • -?, -h, --help - Help for the command.
Tip

You can use the --what-if option to determine whether an item would be overridden, and to identify its storage location.

Examples:

Clean up all eligible items

Command:

bash
dotnet sitecore itemres cleanup

Output:

text
Starting cleaning up databases.
Processing...
Cleaning up databases is finished:
Cleanup of resource items is finished for 'master' database. Removed: 13 item(s).
Cleanup of resource items is finished for 'core' database. Removed: 3 item(s).

Force cleanup without field comparison

Command:

bash
dotnet sitecore itemres cleanup --force

Output:

text
Starting cleaning up databases.
Processing...
Cleaning up databases is finished:
Cleanup of resource items is finished for 'master' database. Removed: 1 item(s).
[master] [D] /sitecore/content/item1 (3d8f6795-1c4e-462d-8a81-be27b1aec5bd)
Cleanup of resource items is finished for 'core' database. Removed: 1 item(s).
[core] [D] /sitecore/content/item1 (3d8f6795-1c4e-462d-8a81-be27b1aec5bd)

Simulate cleanup without deleting items

Command:

bash
dotnet sitecore itemres cleanup --what-if

Output:

text
What if mode is active. No changes will be made.
Starting cleaning up databases.
Processing...
Cleaning up databases is finished:
Cleanup of resource items is finished for 'master' database. Removed: 1 item(s).
[master] [D] /sitecore/content/ItemResCleanUpContent (6f0a7dcd-5a69-409f-bf58-8ee64eda4515)
Cleanup of resource items is finished for 'core' database. Removed: 0 item(s).

Force cleanup for a specific item path

Command:

bash
dotnet sitecore itemres cleanup --path /sitecore/content/ItemResCleanUpContent --force

Output:

text
Starting cleaning up databases.
Processing...
Cleaning up databases is finished:
Cleanup of resource items is finished for 'master' database. Removed: 1 item(s).
[master] [D] /sitecore/content/ItemResCleanUpContent (6f0a7dcd-5a69-409f-bf58-8ee64eda4515)
Cleanup of resource items is finished for 'core' database. Removed: 0 item(s).
If you have suggestions for improving this article, let us know!