---
title: "The cloud environment command"
slug: "the-cloud-environment-command"
abstract: "Reference for the Sitecore CLI cloud environment command for managing SitecoreAI environments."
---
# The cloud environment command

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

> [!note]
> Use the `editinghost` command to [manage editing hosts](https://doc.sitecore.com/sai/en/developers/sitecoreai/sitecore-command-line-interface/sitecore-cli-command-reference/the-cli-cloud-command/the-cloud-editinghost-command.html "The cloud editinghost command").

## Usage

You can use the `cloud environment` command as follows:

```shell
dotnet sitecore cloud environment [subcommand] [options]
```

## Subcommands

You can use the following subcommands:

- `list` - lists all the environments and editing hosts 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 environment.
- `delete` - deletes an existing environment.
- `connect` - establishes the connection information for an environment.
- `disconnect` - removes the connection information from an environment.
- `promote` - promotes an existing [deployment](https://doc.sitecore.com/sai/en/developers/sitecoreai/sitecore-command-line-interface/sitecore-cli-command-reference/the-cli-cloud-command/the-cloud-deployment-command.html "The cloud deployment command") into an environment. Only available to projects using the legacy coupled deployment model.
- `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 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 environments and editing hosts 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:

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

### The info subcommand

The `info` subcommand provides information about a specific 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:

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

### The create subcommand

You can create a new 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. |
| --cm-only | Creates an authoring environment without an editing host.<br><br>**Note**<br>To apply the configuration from `xmcloud.build.json` and deploy required secrets, such as the *Editing Secret*, you must deploy your SitecoreAI project using the `dotnet sitecore cloud deployment` command. |

For example:

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

### The update subcommand

The `update` subcommand updates an existing 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:

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

### The delete subcommand

The `delete` subcommand removes an 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:

```shell
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 |
| --- | --- |
| -aw, --allow-write | A Boolean parameter specifying if writing (pushing) data to the SitecoreAI environment is allowed. <br> Default: False. |
| --audience | Specifies the audience for authentication to the Sitecore Cloud system and Organization. In production, provide one of the following audiences:<br><br>- To access the environment, https://api.sitecorecloud.io. <br>- To access the Sitecore deployment using the XM Cloud DevEx plugin, https://xmcloud-cm.sitecorecloud.io. |
| --auth, --authority | Specifies the Identity Server used to authenticate to the Sitecore Cloud system and Organization.<br>Default: the value set with the SaaS Identity auth URL. |
| --client-credentials, --non-interactive | Boolean parameter to indicate if the authentication should be executed in an interactive or non-interactive flow |
| --client-id | Specifies the client ID used for the Sitecore Cloud system and Organization authentication. |
| --client-secret | Specifies the client secret used for authentication to the Sitecore Cloud system and Organization. |
| --environment-id, -id | Required. The unique identifier of the environment used to establish a connection. |
| -host, --cm-host | Sitecore cm url/hostname |
| --config | Path to the folder containing the `sitecore.json` file.<br>Default: the root directory of the Sitecore project solution. |
| --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:

```shell
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:

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

### The promote subcommand

> [!note]
> The `promote` command is only available to projects using the legacy coupled deployment model.

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.<br><br>**Note**<br>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:

```shell
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.<br>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:

```shell
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:

```shell
dotnet sitecore cloud environment log download --environment-id <env-id> --logfile <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. |
| --logfile | 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:

```shell
dotnet sitecore cloud environment log view --environment-id <env-id> --logfile <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 environment.

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

| Option | Description |
| --- | --- |
| --environment-id, -id | Required. Unique identifier for a SitecoreAI 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:

```shell
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 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 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`, `EH`, `<host name defined in xmcloud.build.json>`, and `null`/omitted. For Editing Host variables, use `--target EH` rather than omitting the option to ensure the variable is scoped correctly during deployment. |
| --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:

```shell
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 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 a SitecoreAI 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:

```shell
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.

> [!note]
> **XM Cloud is now SitecoreAI**
> Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

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

You can use the following options with the subcommand:

| Option | Description |
| --- | --- |
| --environment-id, -id | Required. Unique identifier for a SitecoreAI Environment. |
| --json | Changes the default text formatted response to a JSON format. |
| --config | Path to the folder containing the sitecore.json file.<br>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. |