Skip to content

Document replicated profile command for authenticating with the cli #3651

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
paigecalvert merged 3 commits into from
Nov 14, 2025
Merged

Document replicated profile command for authenticating with the cli #3651

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1d23b85
Document replicated profile command for authenticating with the cli
paigecalvert Nov 14, 2025
23791b5
edit installing replicated cli to clarify install env options
paigecalvert Nov 14, 2025
c5d32d1
small edit
paigecalvert Nov 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/partials/replicated-cli/_authorize-with-token-note.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
:::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](/reference/replicated-cli-installing#env-var).

@paigecalvert paigecalvert Nov 14, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed this second sentence, which implies that there are only two options (login or env var). Instead, this note can just explain what the login command does and not worry about listing the other auth options

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.
:::
27 changes: 4 additions & 23 deletions docs/partials/replicated-cli/_install-docker.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@
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).
:::

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

@paigecalvert paigecalvert Nov 14, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ moved this to a note in the procedure

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).
Expand All @@ -12,25 +10,8 @@ To install and run the latest Replicated CLI in Docker environments:

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. Authorize the Replicated CLI:

- Through a Docker container:

```shell
docker run \
-e REPLICATED_API_TOKEN=$TOKEN \
replicated/vendor-cli --help
```
Replace `TOKEN` with your API token.

- On Windows:

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

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

For more information about the `docker run` command, see [docker run](https://docs.docker.com/engine/reference/commandline/run/) in the Docker documentation.

@paigecalvert paigecalvert Nov 14, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ replaced this step with a link to the more detailed documentation on authenticating with the replicated cli

:::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).
:::
113 changes: 88 additions & 25 deletions docs/reference/replicated-cli-installing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,16 @@ 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 and Run
## Install

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)

@paigecalvert paigecalvert Nov 14, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed "useful for windows" since we recommend WSL for windows users

* On Windows Subsystem for Linux (WSL)

@paigecalvert paigecalvert Nov 14, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ this was missing from the list

* Through Docker (Useful for GitHub Actions or computers without sufficient access)

### MacOS

Expand All @@ -39,11 +41,7 @@ To install and run the latest Replicated CLI on MacOS:

1. <Verify/>

1. <Login/>

<AuthToken/>

1. <Logout/>

@paigecalvert paigecalvert Nov 14, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ also replaced with link to detailed info about the different auth options

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}

Expand All @@ -57,33 +55,77 @@ To install and run the latest Replicated CLI on Linux or Windows Subsystem for L

1. <Verify/>

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

<AuthToken/>
### Docker

1. <Logout/>
<InstallDocker/>

### Docker / Windows
## Authenticate {#auth}

@paigecalvert paigecalvert Nov 14, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ update this page with an overview of the different authentication options: login, env var, profile


<InstallDocker/>
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

## (Optional) Set Environment Variables {#env-var}
# List all profiles
replicated profile ls

The Replicated CLI supports setting the following environment variables:
# Switch to production profile
replicated profile use prod

* **`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:
# Use development profile for a single command
replicated app ls --profile=dev

* 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.
# Edit a profile's token
replicated profile edit dev --token=new-dev-token

* 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.
# Remove a profile
replicated profile rm dev

* **`REPLICATED_APP`**: The slug of the target application.
# Add profiles for different accounts
replicated profile add company-a --token=token-a
replicated profile add company-b --token=token-b

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.
# Switch between accounts
replicated profile use company-a
replicated app ls # Lists apps for company-a

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

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

@paigecalvert paigecalvert Nov 14, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ link to profile cli docs for more details


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

Expand Down Expand Up @@ -113,13 +155,21 @@ To set the `REPLICATED_API_TOKEN` environment variable:
replicated/vendor-cli --help
```

### `REPLICATED_APP`
#### 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. 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. 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 for the target application that you retreived in the previous step:
1. Set the environment variable, replacing `APP_SLUG` with the slug that you copied in the previous step:

* **MacOs or Linux**:

Expand All @@ -134,6 +184,7 @@ To set the `REPLICATED_APP` environment variable:
-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**:

Expand All @@ -142,3 +193,15 @@ To set the `REPLICATED_APP` environment variable:
-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/>
14 changes: 3 additions & 11 deletions docs/vendor/environment-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ sudo mv linux-amd64/helm /usr/local/bin/helm

The Replicated CLI is the primary interface for the Replicated Platform. With the Replicated CLI, you can create and manage applications, releases, channels, customers, and more. You also use the Replicated CLI to create clusters with the Compatibility Matrix.

After installing, you can authorize the Replicated CLI by logging in to your Replicated vendor account through the `replicated login` command.
After installing, authorize the Replicated CLI using your Replicated credentials. See [Authenticate](#auth) in _Install the Replicated CLI_.

@paigecalvert paigecalvert Nov 14, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ from the Set Up Your Environment page in the getting started docs, link to the info about auth rather than telling people to just use the login command


For more information about installing and authorizing the Replicated CLI, see [Install the Replicated CLI](/reference/replicated-cli-installing).

Expand All @@ -111,11 +111,7 @@ To install and run the latest Replicated CLI on MacOS:

1. <Verify/>

1. <Login/>

<AuthToken/>

1. <Logout/>
1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth) in _Install the Replicated CLI_.

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

Expand All @@ -129,11 +125,7 @@ To install and run the latest Replicated CLI on Linux or Windows Subsystem for L

1. <Verify/>

1. <Login/>

<AuthToken/>

1. <Logout/>
1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth) in _Install the Replicated CLI_.

#### Docker / Windows

Expand Down
4 changes: 2 additions & 2 deletions docs/vendor/releases-creating-cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ For information about creating and managing releases with the Vendor API v3, see

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

* Install the Replicated CLI and then log in to authorize the CLI. See [Install the Replicated CLI](/reference/replicated-cli-installing).
* Install the Replicated CLI then authenticate with your Replicated credentials. See [Install the Replicated CLI](/reference/replicated-cli-installing).

* Create a new application using the `replicated app create APP_NAME` command. You only need to do this procedure one time for each application that you want to deploy. See [`app create`](/reference/replicated-cli-app-create) in _Reference_.
* 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_.

Expand Down
18 changes: 12 additions & 6 deletions docs/vendor/replicated-api-tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ import TeamTokenNote from "../partials/vendor-api/_team-token-note.mdx"

This topic describes the available types of API tokens and how to generate them for use with the Replicated CLI and Replicated Vendor API v3.

The Replicated CLI also supports creating multiple authentication profiles for managing tokens across different accounts or environments. For more information, see [Authenticate](/reference/replicated-cli-installing#auth) in _Installing the Replicated CLI_.

## About API Tokens

The Vendor API v3 is the API that manages applications in the Replicated Vendor Portal. The Replicated CLI is an implementation of the Vendor API v3.
Expand Down Expand Up @@ -64,9 +66,11 @@ To generate a service account:

1. Copy the service account token and save it in a secure location. The token will not be available to view again.

:::note
To remove a service account, select **Remove** for the service account that you want to delete.
:::
1. (Recommended) Add the token to a Replicated authentication profile. See [Authenticate](/reference/replicated-cli-installing#auth) in _Installing the Replicated CLI_.

@paigecalvert paigecalvert Nov 14, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ in the how-to on generating API token from the Vendor Portal, add a step to recommend that people add their token to a profile

(This is an assumption on my part that this would be something we want to recommend)


:::note
To remove a service account, select **Remove** for the service account that you want to delete.
:::

### Generate a User API Token

Expand All @@ -93,6 +97,8 @@ To generate a user API token:

1. Copy the user API token that displays and save it in a secure location. The token will not be available to view again.

:::note
To revoke a token, select **Revoke token** for the token that you want to delete.
:::
1. (Recommended) Add the token to a Replicated authentication profile. See [Authenticate](/reference/replicated-cli-installing#auth) in _Installing the Replicated CLI_.

:::note
To revoke a token, select **Revoke token** for the token that you want to delete.
:::