The cloud environment command

The XM Cloud plugin for Sitecore CLI provides the cloud environment command to help you manage environments for your XM Cloud projects.

Usage

You can use the cloud environment command as follows:

RequestResponse

dotnet sitecore cloud environment [subcommand] [options]

Subcommands

You can use the following subcommands:

list - lists all the environments for the connected organization.
info - displays information about a specific environment.
create - creates a new environment within the connected organization.
update - updates settings on an existing XM Cloud environment.
delete - deletes an existing XM Cloud environment.
connect - establishes the connection information for an XM Cloud environment.
disconnect - removes the connection information from an XM Cloud environment.
promote - promotes an existing deployment into an environment.
log list - lists the log file names from the deployment of the specified environment.
log download - downloads and saves the content of the specified log file.
log view - downloads and prints the content of the specified log file to the console.
health - displays the health status of environment resources.
variable list - lists all the variables for an XM Cloud environment.
variable upsert - creates or updates an environment variable.
variable delete - deletes an environment variable.
restart - restarts the authoring environment without downtime.

The list subcommand

The list subcommand lists all the XM Cloud environments for a project. You must provide the project ID.

You can use the following options with the list subcommand:

Option	Description
`--json`	If present, changes the response format from plain text to JSON.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.

For example:

RequestResponse

dotnet sitecore cloud environment list --project-id <project ID>

The info subcommand

The info subcommand provides information about a specific XM Cloud environment. You must provide a unique identifier for the environment.

You can use the following options with the get subcommand:

Option	Description
`--environment-id`, `-id`	Required. The unique identifier for the environment.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.

For example:

RequestResponse

dotnet sitecore cloud environment info --environment-id <environment-id>

The create subcommand

You can create a new XM Cloud environment using the create subcommand. You must specify the name of your new environment and the unique identifier of the parent project.

You can use the following options with the create subcommand:

Option	Description
`--name`, `-n`	Required. The name of the new environment.
`--project-id`	Required. The unique identifier for the project the environment belongs to.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.
`--timeout`	The time in seconds to wait for the creation process to finish. The default is 100.

For example:

RequestResponse

dotnet sitecore cloud environment create --name "Staging" --project-id <project-id>

The update subcommand

The update subcommand updates an existing XM Cloud environment. You must specify the unique identifier for the environment and the information to update.

You can use the following options with the update subcommand:

Option	Description
`--environment-id`, `-id`	Required. The unique identifier of the environment to update.
`--name`, `-n`	Required. The new name of the environment.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.

For example:

RequestResponse

dotnet sitecore cloud environment update --environment-id <env-id> --name "Updated Name"

The delete subcommand

The delete subcommand removes an XM Cloud environment. You must specify the unique identifier for the environment.

You can use the following options with the delete subcommand:

Option	Description
`--environment-id`, `-id`	Required. The unique identifier of the environment to delete.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.

For example:

RequestResponse

dotnet sitecore cloud environment delete --environment-id <environment-id>

The connect subcommand

You can connect your Sitecore solution to an existing environment using the connect subcommand.

You can use the following options with the connect subcommand:

Option	Description
`--environment-id`, `-id`	Required. The unique identifier of the environment used to establish a connection.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.

For example:

RequestResponse

dotnet sitecore cloud environment connect --environment-id <environment-id>

The disconnect subcommand

You can disconnect your Sitecore solution from an existing environment using the disconnect subcommand.

You can use the following options with the disconnect subcommand:

Option	Description
`--environment-id`, `-id`	The unique identifier of the environment you disconnect from the solution.
`--name`, `-n`	The name of the environment.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.

For example:

RequestResponse

sitecore cloud environment disconnect --environment-id <environment-id>

The promote subcommand

You can use the promote subcommand to promote an existing deployment into a specific environment.

You can use the following options with the promote subcommand:

Option	Description
`--environment-id`, `-id`	Required. The unique identifier of the target environment.
`--source-id`, `-s`	Required. The unique identifier of the source deployment for the promotion. Note The image created for the source deployment is applied to the specified environment. Promoting a deployment does not rebuild the deployment.
`--no-watch`	When used, the deployment status/progress information does not display during the deployment process, and the deployment command detaches instantly.
`--no-start`	When used, the deployment entity is created without starting the deployment process.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.

For example:

RequestResponse

sitecore cloud environment promote --environment-id <environment-id> --source-id <deployment-id>

The log list subcommand

The log list subcommand lists the log file names from the deployment of the specified environment.

You can use the following options with the log list subcommand:

Option	Description
`--environment-id`, `-id`	Required. The unique identifier of the environment.
`--latest`	If `true`, it displays only the latest logs for each type of log file. Default: `false`.
`--json`	Change the default response from plain text to JSON.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.

For example:

RequestResponse

dotnet sitecore cloud environment log list --environment-id <env-id>

The log download subcommand

The log download subcommand downloads and saves the content of the specified log file.

You can use the following options with the log download subcommand:

Option	Description
`--environment-id`, `-id`	Required. The unique identifier of the environment.
`--logfile`, `-log`	Required. The unique file name identifier for the file to download.
`--path`. `--outputpath`, `-o`	Required. The path for saving the file.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.
`--timeout`	The time in seconds to wait for the download process to finish. The default is 100.

For example:

RequestResponse

dotnet sitecore cloud environment log download --environment-id <env-id> --filename <filename>

The log view subcommand

The log view subcommand downloads and prints the content of the specified log file to the console.

You can use the following options with the log view subcommand:

Option	Description
`--environment-id`, `-id`	Required. The unique identifier of the environment.
`--filename`	Required. The unique file name identifier for the file to download.
`-?`, `-h`, `--help`	Display developer help and usage information about the command.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.

For example:

RequestResponse

dotnet sitecore cloud environment log view --environment-id <env-id> --filename <filename>

The health subcommand

The health subcommand displays the health status of an environment's resources.

You can use the following options with the health subcommand:

Option

Description

--environment-id, -id

Required.

The unique identifier of the environment.

--json

Changes the default text formatted response to a JSON format.

--trace, -t

Write diagnostics and detailed information about the command.

The variable list subcommand

The variable list subcommand lists all the environment variables for an XM Cloud environment.

You can use the following options with the variable list subcommand:

Option	Description
`--environment-id`, `-id`	Required. Unique identifier for an XM Cloud Environment.
`--json`	Changes the default text formatted response to a JSON format.
`--help`, `-h`, `-?`	Displays help and usage information about the command.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.

For example:

RequestResponse

dotnet sitecore cloud environment variable list --environment-id env1
Found 3 variable(s)
LOG_LEVEL_VALUE Environment variable detailed information:
LOG_LEVEL_VALUE Environment variable detailed information:
Name   : LOG_LEVEL_VALUE
Secret : False
Value  : INFO
Target : CM

Sitecore_GraphQL_ExposePlayground Environment variable detailed information:
Name   : Sitecore_GraphQL_ExposePlayground
Secret : False
Value  : false
Target : *

SITECORE_SPE_ELEVATION Environment variable detailed information:
Name   : SITECORE_SPE_ELEVATION
Secret : False
Value  : BLOCK
Target : Default

SECRET_VARIABLE Environment variable detailed information:
Name   : SECRET_VARIABLE
Secret : True
Value  : *****
Target : CM

The variable upsert subcommand

The variable upsert subcommand creates or updates environment variables for an XM Cloud environment.

Important

Adding or modifying environment variables requires a rebuild/redeploy of your environment for the changes to take effect.

You can use the following options with the variable upsert subcommand:

Option	Description
`--environment-id`, `-id`	Required. Unique identifier for the target XM Cloud Environment.
`--name`, `-n`	Required. The name of the variable. It must be unique within the environment.
`--value`, `-val`	Required. The value of the variable.
`--target`	The target of the environment variable. The variable can be added for the content management instance or the rendering host. Possible values: `CM`, `<rendering-host-name>`
`--secret`, `-s`	Boolean. Indicates you want an encrypted environment variable.
`--help`, `-h`, `-?`	Displays help and usage information about the command.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.

For example:

RequestResponse

dotnet sitecore cloud environment variable upsert --environment-id env1 --name testvar --value testval --target CM
'testvar' Environment variable was accepted for upsert within 'env1' Environment.

The variable delete subcommand

The variable delete subcommand deletes the specified environment variable from an XM Cloud environment.

Important

Deleting environment variables requires a rebuild/redeploy of your environment for the changes to take effect.

You can use the following options with the variable delete subcommand:

Option	Description
`--environment-id`, `-id`	Required. Unique identifier for an XM Cloud Environment
`--name`, `-n`	Required. The name of the variable targeted for deletion.
`--help`, `-h`, `-?`	Displays help and usage information about the command.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.

For example:

RequestResponse

dotnet sitecore cloud environment variable delete --environment-id env1 --name testvar
'testvar' Environment variable was deleted within 'env1' Environment.

The restart subcommand

The restart subcommand restarts the authoring environment without downtime. The subcommand is available in the Sitecore CLI XM Cloud plugin version 1.1.73 or later.

Tip

To update the plugin, change the plugin entry in the sitecore.json file from "Sitecore.DevEx.Extensibility.XMCloud@<older_version>" to "[email protected]".

You can use the following options with the subcommand:

Option	Description
`--environment-id`, `-id`	Required. Unique identifier for an XM Cloud Environment.
`--json`	Changes the default text formatted response to a JSON format.
`--config`	Path to the folder containing the `sitecore.json` file. Default: the root directory of the Sitecore project solution.
`--help`, `-h`, `-?`	Displays help and usage information about the command.
`--verbose`, `-v`	Write additional information about the command.
`--trace`, `-t`	Write diagnostics and detailed information about the command.

Do you have some feedback for us?

If you have suggestions for improving this article,