# 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](/vendor/vendor-portal-creating-account).
- To run on Linux or Mac, install [curl](https://curl.haxx.se/).
- To run through a Docker container, install [docker](https://www.docker.com).
- (Recommended) For Windows users, install Linux on Windows using WSL2. See [How to install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install).

## 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. <InstallMac/>

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

1. <Verify/>

1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth).

### Linux / Windows Subsystem for Linux (WSL) {#linux-wsl2}

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](https://learn.microsoft.com/en-us/windows/wsl/install).

1. <InstallLinux/>

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

1. <Verify/>

1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth).

### 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)](#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](/vendor/replicated-api-tokens).

1. Get the latest Replicated CLI installation files from the [replicatedhq/replicated repository](https://github.com/replicatedhq/replicated/releases) 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.

1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](/reference/replicated-cli-installing#auth).

   :::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](/reference/replicated-cli-installing#env-var).
   ::: 

## Authenticate {#auth}

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 {#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:

```bash
# 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](/reference/replicated-cli-profile).

### Set Environment Variables {#env-var}

#### 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](/vendor/replicated-api-tokens).

1. 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 {#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](https://vendor.replicated.com), go to the **Application Settings** page and copy the slug for the target application. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Application_.

1. 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](https://docs.docker.com/engine/reference/commandline/run/) in the Docker documentation.

    * **Windows**:

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

### `replicated login` {#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](#profiles) or [Set Environment Variables](#env-var).

To authenticate using `replicated login`:

1. <Login/>

1. <Logout/>