Skip to main content

Install the Replicated CLI

This topic describes how to install and run the Replicated CLI.

You can use the Replicated CLI to manage your applications with Replicated programmatically, rather than using the Replicated Vendor Portal.

Prerequisites​

Complete the following prerequisites before installing the Replicated CLI:

Install and Run​

You can install and run the Replicated CLI in the following environments:

  • Directly on MacOS
  • Directly on Linux
  • Through Docker (Useful for Windows, GitHub Actions, or computers without sufficient access)

MacOS​

To install and run the latest Replicated CLI on MacOS:

  1. Run one of the following commands:

    • With Brew:

      brew install replicatedhq/replicated/cli

    • Without Brew:

      curl -Ls $(curl -s https://api.github.com/repos/replicatedhq/replicated/releases/latest \
        | grep "browser_download_url.*darwin_all.tar.gz" \
        | cut -d : -f 2,3 \
        | tr -d \") -o replicated.tar.gz
      tar xf replicated.tar.gz replicated && rm replicated.tar.gz
      mv replicated /usr/local/bin/replicated
    note

    If you do not have root access to the /usr/local/bin directory, you can install with sudo by running sudo mv replicated /usr/local/bin/replicated instead of mv replicated /usr/local/bin/replicated.

  2. Verify that the installation was successful:

    replicated --help

  3. Authorize the Replicated CLI:

    replicated login

    In the browser window that opens, complete the prompts to log in to your vendor account and authorize the CLI.

    Authorize replicated cli web page

    View a larger version of this image

    note

    The replicated login command creates a token after you log in to your vendor account in a browser and saves it to a config file. Alteratively, if you do not have access to a browser, you can set the REPLICATED_API_TOKEN environment variable to authenticate. For more information, see (Optional) Set Environment Variables.

  4. (Optional) When you are done using the Replicated CLI, remove any stored credentials created by the replicated login command:

    replicated logout

Linux / Windows Subsystem for Linux (WSL)​

To install and run the latest Replicated CLI on Linux or Windows Subsystem for Linux (WSL):

  1. For Windows users, first install Linux on Windows using WSL2. See How to install Linux on Windows with WSL.

  2. Run the following command:

    version=$(curl -s https://api.github.com/repos/replicatedhq/replicated/releases/latest \
      | grep -m1 -Po '"tag_name":\s*"v\K[^"]+')
    curl -Ls \
      "https://github.com/replicatedhq/replicated/releases/download/v${version}/replicated_${version}_linux_amd64.tar.gz" \
      -o replicated.tar.gz
    tar xf replicated.tar.gz replicated && rm replicated.tar.gz
    mv replicated /usr/local/bin/replicated
    note

    If you do not have root access to the /usr/local/bin directory, you can install with sudo by running sudo mv replicated /usr/local/bin/replicated instead of mv replicated /usr/local/bin/replicated.

  3. Verify that the installation was successful:

    replicated --help

  4. Authorize the Replicated CLI:

    replicated login

    In the browser window that opens, complete the prompts to log in to your vendor account and authorize the CLI.

    Authorize replicated cli web page

    View a larger version of this image

    note

    The replicated login command creates a token after you log in to your vendor account in a browser and saves it to a config file. Alteratively, if you do not have access to a browser, you can set the REPLICATED_API_TOKEN environment variable to authenticate. For more information, see (Optional) Set Environment Variables.

  5. (Optional) When you are done using the Replicated CLI, remove any stored credentials created by the replicated login command:

    replicated logout

Docker / Windows​

note

For Windows users, Replicated recommends using Windows Subsystem for Linux (WSL2) and installing the Replicated using the Linux installations above. See Linux / Windows Subsystem for Linux (WSL2).

Installing in Docker environments requires that you set the REPLICATED_API_TOKEN environment variable to authorize the Replicated CLI with an API token. For more information, see (Optional) Set Environment Variables.

To install and run the latest Replicated CLI in Docker environments:

  1. Generate a service account or user API token in the vendor portal. To create new releases, the token must have Read/Write access. See Generating API Tokens.

  2. Get the latest Replicated CLI installation files from the replicatedhq/replicated repository on GitHub.

    Download and install the files. For simplicity, the usage in the next step is represented assuming that the CLI is downloaded and installed to the desktop.

  3. Authorize the Replicated CLI:

    • Through a Docker container:

      docker run \
        -e REPLICATED_API_TOKEN=$TOKEN \
        replicated/vendor-cli --help

      Replace TOKEN with your API token.

    • On Windows:

      docker.exe run \
        -e REPLICATED_API_TOKEN=%TOKEN% \
        replicated/vendor-cli --help

      Replace TOKEN with your API token.

For more information about the docker run command, see docker run in the Docker documentation.

(Optional) Set Environment Variables​

The Replicated CLI supports setting the following environment variables:

  • REPLICATED_API_TOKEN: A service account or user API token generated from a vendor portal team or individual account. The REPLICATED_API_TOKEN environment variable has the following use cases:

    • To use Replicated CLI commands as part of automation (such as from continuous integration and continuous delivery pipelines), authenticate by providing the REPLICATED_API_TOKEN environment variable.

    • To authorize the Replicated CLI when installing and running the CLI in Docker containers.

    • Optionally set the REPLICATED_API_TOKEN environment variable instead of using the replicated login command to authorize the Replicated CLI in MacOS or Linux environments.

  • REPLICATED_APP: The slug of the target application.

    When using the Replicated CLI to manage applications through your vendor account (including channels, releases, customers, or other objects associated with an application), you can set the REPLICATED_APP environment variable to avoid passing the application slug with each command.

REPLICATED_API_TOKEN​

To set the REPLICATED_API_TOKEN environment variable:

  1. Generate a service account or user API token in the vendor portal. To create new releases, the token must have Read/Write access. See Generating API Tokens.

  2. Set the environment variable, replacing TOKEN with the token you generated in the previous step:

    • MacOs or Linux:

      export REPLICATED_API_TOKEN=TOKEN

    • Docker:

      docker run \
       -e REPLICATED_API_TOKEN=$TOKEN \
       replicated/vendor-cli --help

    • Windows:

      docker.exe run \
        -e REPLICATED_API_TOKEN=%TOKEN% \
        replicated/vendor-cli --help

REPLICATED_APP​

To set the REPLICATED_APP environment variable:

  1. In the vendor portal, go to the Application Settings page and copy the slug for the target application. For more information, see Get the Application Slug in Managing Application.

  2. Set the environment variable, replacing APP_SLUG with the slug for the target application that you retreived in the previous step:

    • MacOs or Linux:

      export REPLICATED_APP=APP_SLUG

    • Docker:

      docker run \
         -e REPLICATED_APP=$APP_SLUG
         replicated/vendor-cli --help

    • Windows:

      docker.exe run \
        -e REPLICATED_APP=%APP_SLUG% \
        replicated/vendor-cli --help