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:

• Create a vendor account. See Create a Vendor Account.
• To run on Linux or Mac, install curl.
• To run through a Docker container, install docker.
• (Recommended) For Windows users, install Linux on Windows using WSL2. See How to install Linux on Windows with WSL.

Install

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

• Directly on MacOS
• Directly on Linux
• On Windows Subsystem for Linux (WSL)
• Through Docker (Useful for 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. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See Authenticate.

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. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See Authenticate.

Docker

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

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. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See Authenticate.

   note

   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 Set Environment Variables.

Authenticate

After installing the Replicated CLI, authenticate with your Replicated credentials using one of the following methods:

• Set the REPLICATED_API_TOKEN environment variable to your API token
• Create a Replicated profile at ~/.replicated/config.yaml to store your API token
• Generate a single authentication token by running replicated login

The Replicated CLI determines which credentials to use for authentication in the following order:

1. REPLICATED_API_TOKEN environment variable. Environment variables take precedence, allowing temporary overrides without modifying stored profiles.
2. Replicated profile passed with the --profile flag. This allows for a per-command override of the default Replicated profile.
3. Default Replicated profile from ~/.replicated/config.yaml
4. Single token auth with replicated login

Add Replicated Profiles

The Replicated CLI supports multiple authentication profiles, allowing you to manage and switch between different API credentials. This is useful when working with multiple Replicated accounts or environments.

Authentication profiles store your API token and can also optionally store custom API endpoints. Profiles are stored securely in ~/.replicated/config.yaml with file permissions 600 (owner read/write only).

The following examples show how to add and work with Replicated profiles:

# Add a production profile using an existing environment variable
replicated profile add prod --token='$REPLICATED_API_TOKEN'

# Add a development profile with a direct token
replicated profile add dev --token=your-dev-token

# List all profiles
replicated profile ls

# Switch to production profile
replicated profile use prod

# Use development profile for a single command
replicated app ls --profile=dev

# Edit a profile's token
replicated profile edit dev --token=new-dev-token

# Remove a profile
replicated profile rm dev

# Add profiles for different accounts
replicated profile add company-a --token=token-a
replicated profile add company-b --token=token-b

# Switch between accounts
replicated profile use company-a
replicated app ls  # Lists apps for company-a

replicated profile use company-b
replicated app ls  # Lists apps for company-b

For more information, see replicated profile.

Set Environment Variables

Set REPLICATED_API_TOKEN

The REPLICATED_API_TOKEN environment variable can be set to a service account or user API token generated from a Vendor Portal team or individual account.

The REPLICATED_API_TOKEN environment variable is required to authorize the Replicated CLI when installing and running the CLI in Docker containers. It is also helpful for running Replicated CLI commands as part of automation in CI/CD pipelines.

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

Set REPLICATED_APP

When using the Replicated CLI to manage applications through your vendor account, you can set the REPLICATED_APP environment variable to the target application slug to avoid having to pass the slug with each command.

To set the REPLICATED_APP environment variable:

1. Get the application slug:

   replicated app ls

   Or, 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 that you copied in the previous step:

   • MacOs or Linux:

     export REPLICATED_APP=APP_SLUG

   • Docker:

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

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

   • Windows:

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

replicated login

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.

Using the replicated login command requires browser access. If you do not have access to a browser, you can authenticate by adding a Replicated profile or setting the REPLICATED_API_TOKEN environment variable instead. See Add Replicated Profiles or Set Environment Variables.

To authenticate using replicated login:

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

   

   View a larger version of this image

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

   replicated logout