# Manage releases with the CLI

This topic describes how to use the Replicated CLI to create and promote releases.

For information about creating and managing releases with the Vendor Portal, see [Manage Releases with the Vendor Portal](/vendor/releases-creating-releases).

For information about creating and managing releases with the Vendor API v3, see the [releases](https://replicated-vendor-api.readme.io/reference/createrelease) section in the Vendor API v3 documentation.

## Prerequisites

Before you create a release using the Replicated CLI, complete the following prerequisites:

* Install the Replicated CLI then authenticate with your Replicated credentials. See [Install the Replicated CLI](/reference/replicated-cli-installing).
  
* If you do not yet have an application in the Replicated Platform, create a new application using the `replicated app create APP_NAME` command. See [`app create`](/reference/replicated-cli-app-create) in _Reference_.

* Set the `REPLICATED_APP` environment variable to the slug of the target application. See [Set Environment Variables](/reference/replicated-cli-installing#env-var) in _Installing the Replicated CLI_.

  **Example**:

  ```bash
  export REPLICATED_APP=my-app-slug
  ```

## Create and promote a release {#dir}

You can use the Replicated CLI to create a release from a local directory that contains the release files.

To create and promote a release:

1. Lint your release files:
 
    ```bash
    replicated release lint --yaml-dir=PATH_TO_RELEASE_DIR
    ```

    Where `PATH_TO_RELEASE_DIR` is the path to the directory with the release files.

    For more information, see [release lint](/reference/replicated-cli-release-lint) and [Linter Rules](/reference/linter).   

1. Do one of the following:

   * **Create and promote the release with one command**:

      ```bash
      replicated release create --yaml-dir PATH_TO_RELEASE_DIR --lint --promote CHANNEL
      ```
      Where:
      * `PATH_TO_RELEASE_DIR` is the path to the directory with the release files.
      * `CHANNEL` is the channel ID or the case sensitive name of the channel.

      For a complete list of options for the command, see [release create](/reference/replicated-cli-release-create).

   * **Create and edit the release before promoting**:

      1. Create the release:

          ```bash
          replicated release create --yaml-dir PATH_TO_RELEASE_DIR
          ```
          Where `PATH_TO_RELEASE_DIR` is the path to the directory with the release files.

          For more information, see [release create](/reference/replicated-cli-release-create).

      1. Edit and update the release as desired:

          ```
          replicated release update SEQUENCE --yaml-dir PATH_TO_RELEASE_DIR
          ```
          Where:
            
          -  `SEQUENCE` is the release sequence number. This identifies the existing release to be updated.
          -  `PATH_TO_RELEASE_DIR` is the path to the directory with the release files.

          For more information, see [release update](/reference/replicated-cli-release-update).

      1. Promote the release when you are ready to test it. Releases cannot be edited after they are promoted. To make changes after promotion, create a new release.

          ```
          replicated release promote SEQUENCE CHANNEL
          ```

          Where:
            
          -  `SEQUENCE` is the release sequence number.
          -  `CHANNEL` is the channel ID or the case sensitive name of the channel.

          For more information, see [release promote](/reference/replicated-cli-release-promote).

## Include release notes {#release-notes}

Release notes are associated with a release when it is promoted to a channel. There are two ways to include release notes:

Use the `--release-notes` flag when creating or promoting a release. This works for all release types, including KOTS, Helm, Embedded Cluster v2, and Embedded Cluster v3.

```bash
replicated release promote SEQUENCE CHANNEL --release-notes "Bug fixes and performance improvements"
```

To pass multiline notes from a file:

```bash
replicated release promote SEQUENCE CHANNEL --release-notes "$(cat release-notes.md)"
```

The `--release-notes` flag is also available on `release create` when creating and promoting in a single step:

```bash
replicated release create --yaml-dir PATH_TO_RELEASE_DIR --promote CHANNEL --release-notes "$(cat release-notes.md)"
```

For more information, see [release create](/reference/replicated-cli-release-create) and [release promote](/reference/replicated-cli-release-promote).

When a release is promoted without explicit release notes (no `--release-notes` flag and no notes entered in the Vendor Portal), the release notes are automatically populated from this field.

## Notify Enterprise Portal users {#notify-users}

When promoting a release, you can send an email notification to customers who have access to the Enterprise Portal. This is useful for letting end customers know that a new version is available for upgrade.

To notify users, pass the `--notify-users` flag when promoting or creating a release:

```bash
replicated release promote SEQUENCE CHANNEL --notify-users
```

Or when creating and promoting in a single step:

```bash
replicated release create --yaml-dir PATH_TO_RELEASE_DIR --promote CHANNEL --notify-users
```

The `--notify-users` flag is also available as a `notify-users` parameter in the [Replicated GitHub Actions](https://github.com/replicatedhq/replicated-actions) for `create-release`.

:::note
Notifications are off by default and must be explicitly opted into per release. Only customers with Enterprise Portal access receive the email. Customers using the Download Portal only are not notified.
:::