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 get --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.

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.

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,